For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Crea una nueva sesión de checkout. Cada elemento del arreglo `items` puede declararse de dos maneras:
- **Con un producto existente** (recomendado): incluye `product_id` (o `price_id` si el producto tiene varios precios) y opcionalmente `quantity`. No envíes `name`, `amount_in_cents`, etc.; el producto ya tiene esa configuración.
- **Con detalles inline**: incluye `name`, `amount_in_cents`, `currency` y los demás campos del cobro. Recurrente creará un producto invisible bajo la cuenta y lo asociará al checkout.
Cuando usas `items`, no envíes `amount_in_cents` en la raíz del payload. El total del checkout se calcula sumando los ítems y debe alcanzar el mínimo de cobro: 500 para GTQ (Q5) o 100 para USD ($1). Un ítem individual, como envío, puede ser menor al mínimo si el total del checkout sí lo cumple.
Ejemplo mínimo con un producto ya creado:
```json
{
"items": [
{ "product_id": "prod_1234567", "quantity": 1 }
],
"success_url": "https://tusitio.com/exito",
"cancel_url": "https://tusitio.com/cancelar"
}
```
### Cuotas en Checkout
En un checkout hospedado, tu integración controla qué opciones de cuotas se muestran con `available_installments`; el comprador escoge entre esas opciones al pagar. No envíes `installments` al crear un checkout para seleccionar la cantidad final de cuotas.
Para que un checkout muestre cuotas necesitas:
- Moneda `GTQ` (las cuotas no aplican en USD).
- Un cobro único (`charge_type: "one_time"`).
- Pagos con tarjeta habilitados en la cuenta, y una cuenta empresarial (las cuentas personales no pueden ofrecer cuotas).
- **No** hace falta que la cuenta esté verificada, ni habilitar nada con el adquirente.
Mientras la cuenta no complete su verificación sí aplica su tope de procesamiento sin verificación (Q500 en GTQ, $50 en USD, acumulado). Si el total del checkout pasa ese tope, `POST /checkouts` responde `422` con `code: amount_exceeds_unverified_limit` y no crea el checkout, porque el comprador se habría topado con el bloqueo de cuenta no verificada en la página de pago. Completa la verificación de la cuenta para quitar el tope.
Si quieres que el checkout solo permita una cantidad específica de cuotas, muestra únicamente esa opción y desactiva el pago con tarjeta de contado:
```json
{
"items": [
{
"name": "Pago en 6 cuotas",
"amount_in_cents": 15000,
"currency": "GTQ",
"charge_type": "one_time",
"quantity": 1,
"payment_method_types": [],
"available_installments": [6]
}
]
}
```
Para que el comprador elija entre varias opciones, envía una lista como `available_installments: [3, 6, 12]`. Para ocultar cuotas, envía `available_installments: []`.
El parámetro `installments` aplica solo en endpoints de cobro directo que lo incluyan, como `POST /terminal_session_commands`, donde tu sistema escoge la cantidad de cuotas. Las cuotas dependen de la moneda, la cuenta, el banco/emisor y la tarjeta del comprador; si la tarjeta no soporta la opción elegida, el cobro puede fallar con `unsupported_installments`.
Authentication
X-SECRET-KEYstring
Tu clave secreta de API.
Una llave de cuenta (`sk_live_...`, `sk_test_...`) opera sobre su propia cuenta y, con `X-ACCOUNT-ID`, sobre sus cuentas conectadas.
Una llave de organización (`sk_org_live_...`, `sk_org_test_...`) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con `X-ACCOUNT-ID`; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde `403` con `code: organization_key_unsupported`.
Request
This endpoint expects an object.
itemslist of objectsOptional
Lista de productos/servicios a incluir en el checkout. Cada item puede usar `product_id` / `price_id` (producto existente) **o** los campos inline (`name`, `amount_in_cents`, `currency`, …). Los dos modos son excluyentes para un mismo item.
modeenumOptional
(Opcional) Modo del checkout. Envía setup para tokenizar una tarjeta sin cobrarla.
Allowed values:
success_urlstringOptionalformat: "uri"
(Opcional) URL a dónde dirigir al comprador después de un pago exitoso
cancel_urlstringOptionalformat: "uri"
(Opcional) URL a dónde dirigir al comprador cuando abandona el checkout
bank_transfer_memostringOptional3-32 characters
(Opcional) Referencia que debe copiar el pagador al hacer una transferencia bancaria. Recurrente la normaliza a letras y números en mayúscula, sin espacios, acentos ni puntuación, y rechaza valores que sean iguales, contengan o estén contenidos en otra referencia activa de la cuenta.
Si la omites, Recurrente genera una referencia legible a partir del nombre del pagador y le agrega un sufijo único.
user_idstringOptional
(Opcional) ID del usuario a quien pertenece el checkout. Prepopula los campos de información de usuario (nombre, email y teléfono del cliente si existe en tu cuenta).
customer_idstringOptional
(Opcional) ID del cliente en tu cuenta. Prepopula los campos de información de usuario (nombre, email y teléfono guardado del cliente). Si envías customer_id y user_id, se usa customer_id.
metadatastring or double or booleanOptional
(Opcional) Metadata del checkout.
expires_atdatetimeOptional
(Opcional) Fecha en la que quieres que el checkout expire, en formato ISO 8601
discount_codestringOptional
(Opcional) Código de descuento/cupón a aplicar al checkout
application_fee_amountintegerOptional
(Opcional, solo LIVE) Comisión de plataforma en centavos, para pagos únicos. Requiere cobrar a nombre de una cuenta conectada (header `X-ACCOUNT-ID`): cuando el cobro se completa, Recurrente transfiere este monto del balance de la cuenta conectada al de tu plataforma. La comisión se puede revertir al reembolsar con `refund_application_fee: true`, y se incluye en la facturación diaria de comisiones (DTE) si la conexión la tiene habilitada. No se puede combinar con `application_fee_percent` ni con un `transfer_setups` de `purpose: platform_commission`.
application_fee_percentdoubleOptional
(Opcional, solo LIVE) Comisión de plataforma como porcentaje del total de cada factura (0–100, hasta 2 decimales), para suscripciones. Requiere cobrar a nombre de una cuenta conectada (header `X-ACCOUNT-ID`): en cada cobro exitoso, Recurrente transfiere ese porcentaje del balance de la cuenta conectada al de tu plataforma mientras la suscripción esté activa. No se puede combinar con `application_fee_amount` ni con un `transfer_setups` de `purpose: platform_commission`.
transfer_setupslist of objectsOptional
(Opcional, solo LIVE) Transferencias automáticas para enrutar fondos a otras cuentas de Recurrente (modelo destino: tú eres el comercio de registro y envías el neto a una cuenta conectada). No está disponible en Sandbox. En pagos únicos envía `amount_in_cents`: un monto fijo que se transfiere una vez, cuando el cobro se completa. En suscripciones envía `amount_percent`: un porcentaje del total de cada factura, que se transfiere en cada cobro exitoso mientras la suscripción esté activa. Para cobrar una comisión de plataforma usa `application_fee_amount` / `application_fee_percent` en su lugar.
Response
Checkout creado exitosamente
idstring
ID único del checkout
statusenum
Estado del checkout
itemslist of objects
Colección completa de filas mutables del checkout. No incluye descuentos, envío, fees ni prorrateos derivados.
bank_transfer_memostring or nullOptional
Referencia normalizada propuesta por la integración. Es null cuando Recurrente generará la referencia al iniciar el pago por transferencia.
total_in_centsintegerOptional
Monto total en centavos (después de descuentos)
subtotal_in_centsintegerOptional
Monto subtotal en centavos (antes de descuentos)
discountobject or nullOptional
Descuento aplicado al checkout (null si no hay descuento)
currencyenumOptional
Moneda del checkout
payment_method_typeslist of enumsOptional
Métodos de pago que se le ofrecerán al comprador en este checkout, ya resueltos según la configuración del producto/cuenta, la moneda y el tipo de cobro: card (tarjeta, pago de contado), bank_transfer (transferencia bancaria), stablecoins (dólares digitales), balance (Balance Recurrente). Las cuotas se exponen por separado en available_installments; card indica pago de contado, así que un checkout puede ofrecer cuotas (available_installments no vacío) sin incluir card.
available_installmentslist of integersOptional
Opciones de cuotas (en meses) disponibles en este checkout, independientes de payment_method_types. Vacío si no se ofrecen cuotas.
live_modebooleanOptional
Si el checkout está en modo producción (true) o prueba (false)
success_urlstringOptional
URL de redirección en caso de pago exitoso
cancel_urlstringOptional
URL de redirección en caso de cancelación
expires_atdatetimeOptional
Fecha de expiración del checkout
created_atdatetimeOptional
Fecha de creación
metadatastring or double or booleanOptional
Metadata personalizada del checkout
custom_fieldslist of objectsOptional
Valores recolectados de los campos personalizados.
Si el checkout tiene múltiples productos, cada producto contribuye sus
propias entradas — la key puede repetirse entre productos. Usa
field_id como identificador canónico al reconciliar valores.
transfer_setupslist of objectsOptional
Configuraciones de transferencia asociadas
application_fee_amountinteger or nullOptional
Comisión de plataforma en centavos (pagos únicos): la suma de las transferencias de comisión del checkout. null cuando no hay comisión.
application_fee_percentdouble or nullOptional
Comisión de plataforma como porcentaje del total de cada factura (suscripciones). null cuando no hay comisión.
latest_intentobject or nullOptional
Último intent unificado asociado. Su id usa el prefijo in_….
paymentobject or nullOptional
Información del pago (si está pagado)
payment_methodobject or nullOptional
Método de pago utilizado
checkout_urlstringOptional
URL del checkout donde el usuario puede pagar
Errors
400
Bad Request Error
422
Unprocessable Entity Error
Crea una nueva sesión de checkout. Cada elemento del arreglo items puede declararse de dos maneras:
Con un producto existente (recomendado): incluye product_id (o price_id si el producto tiene varios precios) y opcionalmente quantity. No envíes name, amount_in_cents, etc.; el producto ya tiene esa configuración.
Con detalles inline: incluye name, amount_in_cents, currency y los demás campos del cobro. Recurrente creará un producto invisible bajo la cuenta y lo asociará al checkout.
Cuando usas items, no envíes amount_in_cents en la raíz del payload. El total del checkout se calcula sumando los ítems y debe alcanzar el mínimo de cobro: 500 para GTQ (Q5) o 100 para USD ($1). Un ítem individual, como envío, puede ser menor al mínimo si el total del checkout sí lo cumple.
Ejemplo mínimo con un producto ya creado:
1
{
2
"items": [
3
{ "product_id": "prod_1234567", "quantity": 1 }
4
],
5
"success_url": "https://tusitio.com/exito",
6
"cancel_url": "https://tusitio.com/cancelar"
7
}
Cuotas en Checkout
En un checkout hospedado, tu integración controla qué opciones de cuotas se muestran con available_installments; el comprador escoge entre esas opciones al pagar. No envíes installments al crear un checkout para seleccionar la cantidad final de cuotas.
Para que un checkout muestre cuotas necesitas:
Moneda GTQ (las cuotas no aplican en USD).
Un cobro único (charge_type: "one_time").
Pagos con tarjeta habilitados en la cuenta, y una cuenta empresarial (las cuentas personales no pueden ofrecer cuotas).
No hace falta que la cuenta esté verificada, ni habilitar nada con el adquirente.
Mientras la cuenta no complete su verificación sí aplica su tope de procesamiento sin verificación (Q500 en GTQ, $50 en USD, acumulado). Si el total del checkout pasa ese tope, POST /checkouts responde 422 con code: amount_exceeds_unverified_limit y no crea el checkout, porque el comprador se habría topado con el bloqueo de cuenta no verificada en la página de pago. Completa la verificación de la cuenta para quitar el tope.
Si quieres que el checkout solo permita una cantidad específica de cuotas, muestra únicamente esa opción y desactiva el pago con tarjeta de contado:
1
{
2
"items": [
3
{
4
"name": "Pago en 6 cuotas",
5
"amount_in_cents": 15000,
6
"currency": "GTQ",
7
"charge_type": "one_time",
8
"quantity": 1,
9
"payment_method_types": [],
10
"available_installments": [6]
11
}
12
]
13
}
Para que el comprador elija entre varias opciones, envía una lista como available_installments: [3, 6, 12]. Para ocultar cuotas, envía available_installments: [].
El parámetro installments aplica solo en endpoints de cobro directo que lo incluyan, como POST /terminal_session_commands, donde tu sistema escoge la cantidad de cuotas. Las cuotas dependen de la moneda, la cuenta, el banco/emisor y la tarjeta del comprador; si la tarjeta no soporta la opción elegida, el cobro puede fallar con unsupported_installments.
Tu clave secreta de API.
Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.
Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.
Lista de productos/servicios a incluir en el checkout. Cada item puede usar product_id / price_id (producto existente) o los campos inline (name, amount_in_cents, currency, …). Los dos modos son excluyentes para un mismo item.
(Opcional) Referencia que debe copiar el pagador al hacer una transferencia bancaria. Recurrente la normaliza a letras y números en mayúscula, sin espacios, acentos ni puntuación, y rechaza valores que sean iguales, contengan o estén contenidos en otra referencia activa de la cuenta.
Si la omites, Recurrente genera una referencia legible a partir del nombre del pagador y le agrega un sufijo único.
(Opcional, solo LIVE) Comisión de plataforma en centavos, para pagos únicos. Requiere cobrar a nombre de una cuenta conectada (header X-ACCOUNT-ID): cuando el cobro se completa, Recurrente transfiere este monto del balance de la cuenta conectada al de tu plataforma. La comisión se puede revertir al reembolsar con refund_application_fee: true, y se incluye en la facturación diaria de comisiones (DTE) si la conexión la tiene habilitada. No se puede combinar con application_fee_percent ni con un transfer_setups de purpose: platform_commission.
(Opcional, solo LIVE) Comisión de plataforma como porcentaje del total de cada factura (0–100, hasta 2 decimales), para suscripciones. Requiere cobrar a nombre de una cuenta conectada (header X-ACCOUNT-ID): en cada cobro exitoso, Recurrente transfiere ese porcentaje del balance de la cuenta conectada al de tu plataforma mientras la suscripción esté activa. No se puede combinar con application_fee_amount ni con un transfer_setups de purpose: platform_commission.
(Opcional, solo LIVE) Transferencias automáticas para enrutar fondos a otras cuentas de Recurrente (modelo destino: tú eres el comercio de registro y envías el neto a una cuenta conectada). No está disponible en Sandbox. En pagos únicos envía amount_in_cents: un monto fijo que se transfiere una vez, cuando el cobro se completa. En suscripciones envía amount_percent: un porcentaje del total de cada factura, que se transfiere en cada cobro exitoso mientras la suscripción esté activa. Para cobrar una comisión de plataforma usa application_fee_amount / application_fee_percent en su lugar.
