TRtrytoku
Checkout Session

Crear Checkout Session

Crea una Checkout Session y devuelve su representación completa, incluida la url a la que se deriva al cliente final para pagar o inscribir un medio de pago.

El campo mode fija qué hace la sesión: PAYMENT cobra deudas o un monto, ENROLLMENT inscribe un medio de pago automático y SAVE_PAYMENT_INSTRUMENT guarda una cuenta bancaria sin cobrar.

Si se envía customer_data sin billing_data.id_customer, el Customer se crea o se actualiza con esos datos. Si se envía invoice_data, se crea una deuda nueva y la sesión queda asociada a ella.

expiration_datetime se interpreta en formato ISO 8601 (sin zona horaria se asume UTC) y no puede quedar en el pasado. Cuando se envía, la sesión se expira de forma automática en esa fecha. Si se omite, la sesión expira según la duración que configure el flujo, sin importar su mode. Si el flujo no configura ninguna, permanece abierta hasta expirarla manualmente.

Cuando la sesión queda asociada a un Customer y no se envía skip_message_trigger, se le manda el enlace de pago por el canal indicado en communication_channel. El envío es best-effort: si falla, la Checkout Session se crea igual. Si en cambio se envía id_template, la plantilla debe existir: si no, la solicitud se rechaza con 400 y la sesión no se crea.

unique_external_id hace la creación idempotente: si la organización vuelve a enviar un valor que ya usó, se devuelve la Checkout Session que ya se creó con él, en el estado en que esté, sin crear una nueva — ni la sesión, ni el Customer, ni la deuda — ni volver a enviarle el enlace al cliente. Sirve para que un reintento por timeout reciba la url de la sesión que sí se creó en vez de generar una segunda. El reintento se valida igual que una creación nueva: si con esos datos ya no se podría crear la sesión, responde el mismo error. El resto de sus campos se ignora, con una sola excepción: un allowed_payment_options con botones reemplaza el filtro de la sesión si sigue abierta y el flow_name es el mismo de la sesión.

allowed_payment_options limita los botones de medio de pago que muestra el checkout.

id_checkout elige el checkout cuya configuración usa la sesión: el de la cuenta en el flujo flow_name o el Default de ese flujo. Un checkout que no sea ninguno de los dos se rechaza con 404. Si se omite, se usa el checkout de la cuenta en el flujo.

post/{country_code}/checkout-sessions

Request

  • Base URL
    https://api.trytoku.com
  • URL
    https://api.trytoku.com/{country_code}/checkout-sessions
  • Auth
    API key in header x-api-key

Path parameters

country_code'cl' | 'mx' | 'br' required

País de la organización sobre la que se opera, como primer segmento de la ruta: cl (Chile), mx (México) o br (Brasil).

Headers

x-api-versionstring date

Versión del API para esta petición, como cualquier fecha YYYY-MM-DD. Fija el contrato de la respuesta; si se omite, se deriva de la fecha de creación de la organización.

Example:2026-10-08

Request body

additional_metadataobject nullable

Datos propios de la organización que se guardan junto a la Checkout Session.

allow_partial_paymentboolean nullable

Indica si el cliente final puede abonar solo una parte del total.

allowed_payment_optionsPaymentOptionFormType[]

Medios de pago que la Checkout Session puede mostrar, uno por botón del checkout (por ejemplo card o transfer_cl); se ocultan los demás. Un botón cubre todos los productos que agrupa. Si ninguno de los botones indicados está en el flujo, la solicitud se rechaza con 400. Vacío o en null no filtra nada. Es el único campo que se aplica cuando se reenvía un unique_external_id ya usado: si trae botones, reemplaza el filtro de la sesión existente mientras siga abierta, siempre que el flow_name sea el de la sesión; si no, responde 400.

communication_channel'mail' | 'sms' | 'wsp'

Canal del motor de comunicaciones.

expiration_datetimestring nullable

Fecha y hora, en formato ISO 8601, en la que la Checkout Session expira. Manda por sobre la duración que el flujo configure para sus enlaces de pago. Si se omite, una sesión PAYMENT expira según esa duración. Si el flujo no configura ninguna, o la sesión no es PAYMENT, permanece abierta hasta expirarla manualmente.

external_idstring nullable

Identificador que entrega la organización para reconocer después la operación.

flow_namestring nullable

Flow con el que se crea la Checkout Session.

form_informationobject nullable

Información no sensible con la que el cliente final completó el formulario.

id_checkoutstring encrypted-id nullable

Checkout cuya configuración usa la sesión. Debe ser el checkout de la cuenta en el flow flow_name o el Default de ese flow. Si no se envía, se usa el checkout de la cuenta en el flow.

id_templatestring encrypted-id nullable

Plantilla con la que se le envía al Customer el mensaje con el enlace de pago. Debe existir.

mode'ENROLLMENT' | 'PAYMENT' | 'SAVE_PAYMENT_INSTRUMENT' required

Modo de una Checkout Session.

skip_message_triggerboolean nullable

Indica si se omite el envío del enlace de pago al Customer.

unique_external_idstring nullable

Identificador propio de la organización que hace idempotente la creación: si se vuelve a enviar un valor ya usado, se devuelve la Checkout Session que ya se creó con él, sin crear una nueva.

Example request

{
  "billing_data": {
    "id_account": "acc_123abc",
    "id_customer": "cus_123abc",
    "id_subscription": "sub_123abc"
  },
  "id_checkout": "chk_123abc",
  "id_template": "tem_123abc"
}

Response

La Checkout Session quedó creada y abierta. Si el unique_external_id ya se había usado, es la Checkout Session que ya se creó con él, en el estado en que esté.

allow_partial_paymentboolean nullable

Indica si el cliente final puede abonar solo una parte del total en lugar de pagarlo completo.

card_flow_configobject nullable

Configuración resuelta para el pago con tarjeta de esta sesión: por qué procesador se cobra, restricciones de tarjetas aceptadas, autenticación 3-D Secure y cuotas. Corresponde al tipo de sesión: un pago único lleva la configuración de pago único, y una inscripción o el guardado de un medio de pago llevan la recurrente. Es nulo cuando no aplica ninguna configuración. Solo de lectura. Toku la resuelve en cada lectura a partir de la configuración de tarjeta de la organización y del mode de la sesión.

combine_activeboolean nullable

Indica si esta Checkout Session tiene una combinación de pagos en curso: ya hay al menos un pago, falta saldo, la sesión sigue abierta y no se cumplió el plazo para devolver lo cobrado. Solo de lectura. Toku lo calcula en cada lectura a partir de los pagos ya hechos sobre la sesión.

combine_enabledboolean nullable

Indica si se le puede ofrecer al cliente final pagar el total en varios pagos. Deja de ser verdadero una vez que hay un pago parcial hecho: para una combinación en curso se usa combine_active. Solo de lectura. Toku lo calcula en cada lectura a partir de la configuración de la organización y del estado de la sesión.

customer_pii_maskedboolean nullable

Indica si los datos personales del Customer (name, mail, phone_number, government_id y external_id) vienen enmascarados. Cuando es true los valores no son utilizables: hay que pedirlos de nuevo antes de enviarlos. Solo de lectura. Toku lo resuelve en cada lectura según la configuración de la organización.

disable_oneclick_checkoutboolean nullable

Indica si en esta Checkout Session se desactiva el pago con un medio ya guardado, aunque la organización lo tenga habilitado.

expiration_datetimestring nullable

Fecha y hora, en formato ISO 8601, en la que la Checkout Session expira.

external_idstring nullable

Identificador que entrega la organización para reconocer después los pagos o inscripciones hechos con esta Checkout Session.

flow_namestring required

Flow con el que se creó la Checkout Session.

id_checkout_sessionstring required

Identificador único de la Checkout Session. Solo de lectura. Toku lo genera al crear la sesión.

is_receipt_redirection_disabledboolean nullable

Indica si el comprobante no redirige al cliente final. El comprobante se muestra igual: lo que se desactiva es la redirección que sale desde él una vez terminada la operación. Solo de lectura. Toku lo calcula en cada lectura: es verdadero mientras la sesión cobre un monto o deudas con un medio de pago que cobra de forma diferida y todavía no tenga un pago exitoso, porque hasta entonces no hay un resultado que mostrar al otro lado.

mode'ENROLLMENT' | 'PAYMENT' | 'SAVE_PAYMENT_INSTRUMENT'

Modo de una Checkout Session.

operation_idstring nullable

Identificador de la operación con la que se completó la Checkout Session. Solo de lectura. Toku lo estampa al completar la sesión; es nulo mientras siga abierta.

redirectionstring nullable

Identificador de la redirección a la que se envía al cliente final al terminar. Solo de lectura. Toku la crea al crear la sesión, a partir del redirection_data de la petición.

session_price_change_origin'adjustment_document' | 'specified_at_creation'

Where a checkout session's price change came from, for portal labelling.

session_price_changes_totalnumber nullable

Suma de los ajustes de precio aplicados solo a esta Checkout Session. Un valor negativo reduce el total a pagar, por ejemplo un crédito a favor; es cero cuando no hay ajustes. Solo de lectura. Toku lo calcula en cada lectura a partir del price_change con el que se creó la sesión y de los saldos a favor del Customer.

statestring required

Estado de la Checkout Session: OPEN mientras se puede pagar, COMPLETED o EXPIRED al cerrarse. Solo de lectura. Lo maneja Toku: la sesión nace OPEN y pasa a COMPLETED cuando se completa la operación o a EXPIRED cuando vence.

unique_external_idstring nullable

Identificador único con el que la organización registró esta Checkout Session. null si no se envió.

urlstring required

Dirección que se le entrega al cliente final para pagar o inscribir el medio de pago.

Changes

No recorded changes to this operation across all 2 revisions of this API.