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.