Skip to navigation
Referencia APICheckouts

Crear un checkout

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:

{
  "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:

{
  "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.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

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. Admite HTTP, HTTPS y deep links de aplicaciones (por ejemplo, miapp://cancelar).

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.

clave_enabledbooleanOptionalDefaults to true

(Opcional) Si el checkout ofrece Clave, la billetera con la que el comprador paga con sus tarjetas guardadas tras confirmar un código por WhatsApp o email. Envía false para que este checkout muestre solo el formulario de tarjeta y los demás métodos de pago: sin tarjetas guardadas, sin oferta de código y sin botón de Clave en el checkout embebido. La tarjeta con la que se pague tampoco se guarda en Clave. No quita los demás métodos de pago: Balance Recurrente sigue disponible si está habilitado, y el comprador entra a su cuenta de Recurrente para usarlo, no con un código de Clave.

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). 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
Allowed values:
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
Allowed values:
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), akisi (efectivo en Akisí; solo cuentas habilitadas, cobros únicos en GTQ con precio fijo y cuentas fuera de Sandbox). 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.

Allowed values:
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)

amount_set_in_browserbooleanOptional

El monto lo fijó el navegador del comprador. Solo en checkouts creados por el botón de Clave en el sitio del comercio, con ítems con monto inline y sin firma del servidor. Compáralo con tu pedido antes de entregar.

clave_enabledbooleanOptional

Si el checkout ofrece Clave (tarjetas guardadas del comprador). false cuando se creó con clave_enabled en 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