Checkout Form: formulario de tarjeta embebido

Checkout Form es un script de JavaScript que monta, dentro de tu propio formulario, los dos campos sensibles de la tarjeta: el número (PAN) y el CVV. Ambos se renderizan en iframes servidos por Toku, así que el dato de la tarjeta nunca pasa por tu frontend ni por tu backend. Tú mantienes el control del diseño y del resto del formulario.

Cada uso del Checkout Form se completa con una Checkout Session: tu backend la crea en la API de Toku y define en ella qué se hace con la tarjeta (cobrar, inscribirla o ambas), el cliente, el monto y si se usa una tarjeta ya guardada. El formulario solo captura la tarjeta y se la entrega a esa sesión con processCheckoutSession.

¿Cuándo usarlo?

Necesitas	Usa
Un formulario de tarjeta con tu propio diseño, dentro de tu sitio	Checkout Form
Que tus clientes gestionen sus deudas y medios de pago	Portal de pagos
Portal de Toku embebido en tu sitio web	Iframe del portal

Operaciones soportadas

La operación la define el mode de la Checkout Session, no el formulario.

Sesión	Qué hace	Qué devuelve en `onSuccess`
`ENROLLMENT`	Inscribe la tarjeta como medio de pago para cobros futuros.	`paymentMethodId` (`pm_…`)
`PAYMENT`	Cobra el monto con la tarjeta, sin inscribirla.	`externalTransactionId` (`trs_…`)
`PAYMENT` con `enable_toggle_switch: true`	Cobra el monto y además inscribe la misma tarjeta.	`externalTransactionId` (`trs_…`); la tarjeta queda inscrita como medio de pago

Cualquiera de estos modos puede llevar selected_card para usar una tarjeta ya guardada del cliente: el formulario se monta sin el campo del número y el cliente solo ingresa CVV y vencimiento.

Cómo funciona

%%{init: {'sequence': {'mirrorActors': false}}}%%
sequenceDiagram
    autonumber
    actor Cliente
    participant Backend as Backend del comercio
    participant Comercio as Frontend del comercio
    participant Iframe as Checkout Form (iframes Toku)
    participant Toku as API de Toku

    Backend->>Toku: Crea la Checkout Session (modo, cliente, monto, tarjeta guardada)
    Toku-->>Backend: id de la Checkout Session
    Backend-->>Comercio: checkoutSessionId
    Comercio->>Iframe: Carga el script y monta los campos PAN y CVV
    Cliente->>Iframe: Escribe número de tarjeta y CVV
    Cliente->>Comercio: Escribe fecha de expiración y nombre
    Comercio->>Iframe: processCheckoutSession(parámetros)
    Iframe->>Toku: Cifra los datos y ejecuta lo que define la sesión
    Toku-->>Iframe: Resultado (o challenge 3DS)
    Iframe-->>Comercio: onSuccess / onError
    Toku-)Backend: Webhook con el resultado

Qué datos maneja cada parte

Dato	Lo captura	Cómo llega a Toku	Obligatorio
Número de tarjeta (PAN)	Iframe de Toku	Nunca sale del iframe	Sí, salvo con tarjeta guardada
CVV	Iframe de Toku	Nunca sale del iframe	Sí
Fecha de expiración	Tu formulario	Se la pasas a `processCheckoutSession`; el script la cifra y la envía junto al PAN y al CVV	Sí
Nombre del titular	Tu formulario	Igual que la fecha de expiración	No
Modo, cliente y monto	Tu backend	En la Checkout Session, con tu API key	Sí

Ambientes

Ambiente	Script	Iframes
`PROD`	`https://storage.googleapis.com/toku-embedded-portal/checkout-form.min.js`	`checkout-form-pan.trytoku.com`, `checkout-form-cvv.trytoku.com`

Los iframes solo se renderizan dentro de los dominios que Toku habilitó para tu organización. Antes de integrar, envía a tu ejecutivo los dominios de prueba y de producción desde los que cargarás el formulario.

Confirmación server-side

El resultado que recibes en onSuccess es informativo. La fuente de verdad es el webhook: payment_method.attached para una inscripción, y transaction.success o transaction.failed para un pago. Cada transacción y medio de pago trae el id_checkout_session de la sesión que lo originó. Para más información acerca de los eventos, revisa: Notificaciones y webhooks.

Disponibilidad

Checkout Form está disponible para organizaciones en México, Chile y Brasil.

Contenido de esta sección

Guía de integración: crear la Checkout Session, montar el formulario y procesarla, paso a paso.
Referencia de TokuCheckoutForm

Deprecado: integración sin Checkout Session (processOperation)

❗️
Integración deprecada
Esta integración se mantiene solo por compatibilidad. Las integraciones nuevas deben usar una Checkout Session y processCheckoutSession.

Antes de la Checkout Session, el frontend indicaba el tipo de operación y sus datos directamente en processOperation(tipo, parámetros). El detalle de sus parámetros está en la sección deprecada de la Guía de integración.

Operación	Qué hace	Qué devuelve en `onSuccess`
`INSCRIPTION`	Inscribe la tarjeta como medio de pago para cobros recurrentes.	`paymentMethodId`
`PAYMENT`	Cobra un monto con la tarjeta ingresada o con una tarjeta ya guardada. Opcionalmente inscribe la tarjeta en el mismo paso.	`externalTransactionId`

Si processOperation recibe un checkoutSessionId, se procesa como processCheckoutSession e ignora el tipo indicado.