---
title: "Preparar el pago de un plan (un mes o un año) con el botón de Payphone por redirección (roles owner/admin)"
method: POST
path: "/pagos/payphone/checkout"
tags: ["pagos"]
---

# Preparar el pago de un plan (un mes o un año) con el botón de Payphone por redirección (roles owner/admin)

`POST /pagos/payphone/checkout`

## Request

- Base URL: `https://contadeo.com/api`
- URL: `https://contadeo.com/api/pagos/payphone/checkout`
- Auth: HTTP bearer

Paga un periodo del `ciclo` elegido: `anual` (precio del catálogo) o `mensual` (el anual entre 10). El monto se calcula en servidor desde el catálogo de planes + IVA 15% (con crédito de prorrateo si aplica). Con `renovacionAutomatica` el cliente consiente guardar la tarjeta: si Payphone entrega el token al confirmar (solo Visa y Mastercard pagadas con tarjeta), las renovaciones se cobran solas cada periodo. El mensual exige `renovacionAutomatica`. Llama al `POST /api/button/Prepare` de Payphone y devuelve `paymentId` más los dos enlaces hospedados. El navegador se redirige TOP-LEVEL a `payWithCard` o `payWithPayPhone`: no se embebe nada, por lo que Contadeo nunca ve el número de tarjeta. Los enlaces CADUCAN A LOS 10 MINUTOS. 400 si el mensual llega sin renovación, si la tarjeta guardada no está disponible, o si se pide mensual con un plan anual vigente de más de 31 días. 409 si el tenant ya tiene una suscripción viva con dLocal. 503 si la pasarela no está configurada o el kill-switch `PAYPHONE_HABILITADO` está apagado. Con `complementos` se suma al importe el precio del complemento (Gestión: 99/año o 9,90/mes sin IVA); renovar sin marcarlo lo RETIRA. 400 también si un complemento no existe, si se pide `tipo: "complemento"` sin un plan de pago vigente con fecha, o si ese complemento ya está activo.

## Request body

- object
  - `plan` 'emprendedor' | 'pyme' | 'empresa', required
  - `ciclo` 'mensual' | 'anual'
  - `renovacionAutomatica` boolean: Guardar la tarjeta y renovar solo. Obligatoria en el mensual.
  - `rucFacturacion` string: RUC al que facturar; si falta, el emisor de la cuenta
  - `complementos` string[]: Complementos que se compran ('gestion' concede ATS, contabilidad y nómina). El precio lo pone el servidor desde el catálogo. Un código desconocido responde 400.
  - `tipo` 'complemento': Con `complemento` se cobra SOLO el complemento, prorrateado por los días que le quedan al periodo ya pagado, y `planExpiraAt` no se mueve. Exige el plan vigente, de pago y con fecha de vencimiento, y complementos que aún no estén activos. Sin este campo el cobro es del plan, con los complementos marcados.

## Response `201`

Enlaces del botón listos; redirigir el navegador a payWithCard o payWithPayPhone

- object
  - `transaccionId` string, uuid
  - `clientTransactionId` string: Referencia propia generada en servidor; vuelve como query param en el redirect
  - `plan` string
  - `paymentId` string: Identificador del intento que devuelve Prepare
  - `payWithCard` string, uri: Enlace hospedado del formulario de tarjeta (redirección top-level)
  - `payWithPayPhone` string, uri: Enlace hospedado para pagar con la app Payphone
  - `montoCentavos` integer: Total con IVA en centavos (base + IVA)
  - `baseCentavos` integer: Base neta cobrada en centavos (sin IVA, ya con crédito de prorrateo aplicado)
  - `ivaCentavos` integer: IVA en centavos
  - `creditoCentavos` integer: Crédito de prorrateo aplicado en centavos; 0 si es renovación o no aplica prorrateo
  - `ciclo` 'mensual' | 'anual'
  - `renovacionAutomatica` boolean
  - `complementos` string[]: Complementos que paga este cobro
  - `tipo` 'alta' | 'renovacion' | 'mejora' | 'complemento': Qué se está cobrando; lo decide el servidor: `alta` (plan free o vencido), `renovacion` (mismo plan), `mejora` (plan superior, con prorrateo) o `complemento` (solo el complemento).

## Other responses

- `400`: Cuerpo inválido o validación de negocio (previene errores SRI 62/52/65/69/39)
- `401`: Token/key ausente, inválido o expirado
- `403`: Rol insuficiente o acceso denegado
- `409`: Conflicto de unicidad
- `503`: Botón de Payphone no configurado o apagado; usar dLocal o activación manual

---

[API](https://skmtc.dev/contadeo/apis/api-de-contadeo.md) · [All operations](https://skmtc.dev/contadeo/apis/api-de-contadeo/llms.txt) · [OpenAPI document](https://skmtc.dev/contadeo/apis/api-de-contadeo/revisions/461bbb9a74ce?raw)