Referencia de TokuCheckoutForm

Referencia completa de la clase TokuCheckoutForm que expone el script. Para el flujo paso a paso revisa la Guía de integración.

Constructor

const form = new TokuCheckoutForm(settings);

Nombre	Tipo	Requerido	Descripción
`environment`	`string`	Sí	Ambiente al que apuntan los iframes. Valor: `PROD`.
`cvvDivId`	`string`	Sí	Id del elemento donde se monta el iframe del CVV. Debe existir al construir el objeto.
`cvvStyle`	`object`	Sí	Estilos inline que se aplican al `<input>` del CVV dentro del iframe. Claves en formato CSS, por ejemplo `'border-radius'`.
`onSuccess`	`function(result)`	Sí	Se llama cuando la operación termina con éxito. Ver onSuccess.
`onError`	`function(error)`	Sí	Se llama cuando la operación falla. Ver onError.
`panDivId`	`string`	No	Id del elemento donde se monta el iframe del número de tarjeta. Si lo omites, el iframe se crea oculto; úsalo así solo para pagar con una tarjeta guardada.
`panStyle`	`object`	No	Estilos inline del `<input>` del número de tarjeta.
`panStylesheet`	`string`	No	CSS que se inyecta como `<style>` dentro del iframe del número de tarjeta.
`cvvStylesheet`	`string`	No	CSS que se inyecta como `<style>` dentro del iframe del CVV.
`options.maskPan`	`boolean`	No	Oculta el número de tarjeta cuando el campo pierde el foco. Por defecto `false`.
`options.panPlaceholder`	`string`	No	Placeholder del campo de número de tarjeta.
`options.cvvPlaceholder`	`string`	No	Placeholder del campo CVV.
`organizationId`	`string`	No	Id público de la organización (`org_…`). Necesario para la validación del BIN.
`accountId`	`string`	No	Id público de la cuenta (`acc_…`). Necesario para la validación del BIN.
`onPanFocus`	`function(form)`	No	El campo de número de tarjeta recibe el foco. Recibe la instancia de `TokuCheckoutForm`.
`onPanBlur`	`function(form)`	No	El campo de número de tarjeta pierde el foco.
`onCvvFocus`	`function(form)`	No	El campo CVV recibe el foco.
`onCvvBlur`	`function(form)`	No	El campo CVV pierde el foco.
`onPanChange`	`function(data)`	No	El cliente cambia el número de tarjeta. Ver onPanChange.
`onCvvChange`	`function(data)`	No	El cliente cambia el CVV. Ver onCvvChange.
`onCardValidationLoading`	`function()`	No	Comienza la validación del BIN.
`onCardValidationCompleted`	`function(data)`	No	Termina la validación del BIN. Ver onCardValidationCompleted.

El constructor lanza un Error si environment no es válido, si falta cvvDivId o cvvStyle, o si los contenedores indicados no existen en el DOM.

Callbacks

onSuccess

{
  "action": "OPERATION_FINISHED",
  "operationResult": "SUCCESS",
  "data": { "externalTransactionId": "…" }
}

Operación	Contenido de `data`
`PAYMENT`	`externalTransactionId`: identificador de la transacción creada.
`INSCRIPTION`	`paymentMethodId`: identificador del medio de pago creado.

onError

{
  "action": "OPERATION_FINISHED",
  "operationResult": "FAILURE",
  "errorCode": "1001",
  "errorMessage": "An unexpected error ocurred"
}

Campo	Descripción
`errorCode`	Los cuatro dígitos del código de respuesta de Toku, sin el prefijo de gravedad. Búscalo en Códigos de pago rechazado para conocer la causa, su gravedad y el mensaje sugerido al cliente. `9999` es un error no clasificado.
`errorMessage`	Texto genérico. En los rechazos del medio de pago no trae el detalle del catálogo, así que no lo muestres al cliente tal cual: usa `errorCode` para obtener el mensaje desde el catálogo.

También se recibe onError cuando la operación no termina dentro de 5 minutos.

onPanChange

{
  "length": 16,
  "cardInstitution": "visa",
  "luhnCheck": true,
  "bin": "411111",
  "last4": "1111"
}

Campo	Tipo	Descripción
`length`	`number`	Dígitos ingresados hasta ahora.
`cardInstitution`	`string`	`visa`, `mastercard`, `americanexpress` o `""` si aún no se reconoce.
`luhnCheck`	`boolean`	`true` si el número ingresado pasa el algoritmo de Luhn.
`bin`	`string`	Primeros seis dígitos. Presente cuando hay suficientes dígitos.
`last4`	`string`	Últimos cuatro dígitos. Presente cuando el número está completo.

onCvvChange

{ "length": 3 }

onCardValidationCompleted

{
  "success": true,
  "country": "MX",
  "type": "credit"
}

Campo	Tipo	Descripción
`success`	`boolean`	`true` si la tarjeta está permitida para la cuenta.
`country`	`string`	País del banco emisor.
`type`	`string`	`credit` o `debit`.

Métodos

processOperation(type, parameters)

Ejecuta una operación con los datos ingresados en los iframes. Valida parameters de forma síncrona y lanza un Error si algo falta o es inválido; el resultado de la operación llega por onSuccess u onError.

Argumento	Tipo	Descripción
`type`	`string`	`PAYMENT` o `INSCRIPTION`.
`parameters`	`object`	Depende del tipo. Ver Operaciones.

setPanStyle(style) / setCvvStyle(style)

Reemplazan los estilos inline del <input> correspondiente. Reciben un objeto con las mismas claves que panStyle y cvvStyle.

changeStyle(panStyle, cvvStyle)

Equivale a llamar setPanStyle y setCvvStyle en una sola operación.

setPanStylesheet(css) / setCvvStylesheet(css)

Inyectan un <style> adicional dentro del iframe correspondiente. Cada llamada agrega una hoja nueva; no reemplaza las anteriores.

Operaciones

PAYMENT

Cobra amount con la tarjeta ingresada o con una tarjeta guardada.

Nombre	Tipo	Requerido	Descripción
`organizationId`	`string`	Sí	Id público de la organización (`org_…`).
`accountId`	`string`	Sí	Id público de la cuenta (`acc_…`).
`amount`	`number`	Sí	Monto a cobrar.
`customerId`	`string`	Sí	Id público del cliente (`cus_…`).
`subscriptionId`	`string`	No	Id público de la suscripción (`sub_…`). Solo si el pago es de invoices.
`expirationDate`	`string`	Sí	Vencimiento en formato `MM/YY`.
`customerName`	`string`	Sí, salvo con `paymentInstrumentId`	Nombre del titular.
`invoiceIds`	`string[]`	No	Deudas que paga este cobro (`in_…`).
`installments`	`number`	No	Número de cuotas. Por defecto `1`.
`tokuProducts`	`string[]`	Sí	Producto Toku con el que se procesa el cobro, por ejemplo `['payment_orchestration_onetime']`. Dejará de ser necesario cuando Toku lo resuelva desde `checkoutSessionId`.
`paymentInstrumentId`	`string`	No	Tarjeta guardada con la que se cobra (`pin_…`). Requiere `expirationDate` y exige omitir `panDivId` en el constructor.
`flowName`	`string`	No	Nombre del flujo de pago, solo si Toku te indicó uno.
`checkoutSessionId`	`string`	No	`checkout_session_id` de la Checkout Session desde la que nace el pago. Recomendado: Toku lo usará para validar la operación y resolver la configuración de la sesión a partir de octubre 2026.

Sin paymentInstrumentId, el constructor debe tener panDivId para que el cliente pueda escribir el número de tarjeta.

Pago identificado solo por la Checkout Session

Disponible a partir de octubre de 2026. Con checkoutSessionId, Toku resolverá customerId, invoiceIds y tokuProducts desde la sesión, y esos campos pasarán a ser opcionales.

form.processOperation('PAYMENT', {
  organizationId: 'org_…',
  checkoutSessionId: 'checkout_session_id de la sesión',
  expirationDate: '09/28',
  customerName: 'Nombre del titular',
});

INSCRIPTION

Inscribe la tarjeta como medio de pago de una suscripción.

Nombre	Tipo	Requerido	Descripción
`organizationId`	`string`	Sí	Id público de la organización (`org_…`).
`accountId`	`string`	Sí	Id público de la cuenta (`acc_…`).
`customerId`	`string`	Sí	Id público del cliente (`cus_…`).
`subscriptionId`	`string`	Sí	Id público de la suscripción (`sub_…`).
`tokuProducts`	`string[]`	Sí	Producto Toku con el que se inscribe, por ejemplo `['cards_batch_mx_recurring_pst']`.
`expirationDate`	`string`	Sí	Vencimiento en formato `MM/YY`.
`customerName`	`string`	Sí	Nombre del titular.

Formato de los ids

Todos los ids son públicos: un prefijo, un guion bajo y 32 caracteres. processOperation rechaza los que no cumplen el formato.

Entidad	Prefijo
Organización	`org_`
Cuenta	`acc_`
Cliente	`cus_`
Suscripción	`sub_`
Invoice	`in_`
Instrumento de pago guardado	`pin_`

Errores de validación

Mensajes que processOperation puede lanzar como Error. Ocurren antes de contactar a Toku, así que no llegan por onError.

Mensaje	Causa
`customerId or subscriptionId is required`	`PAYMENT` sin ninguno de los dos.
`customerId is required`	`INSCRIPTION` sin `customerId`.
`Invalid customerId` / `subscriptionId is not valid` / `Invalid accountId`	El id no cumple el formato.
`organizationId is required` / `accountId is required`	Falta el id.
`amount must be set to validate that it matches invoices amount and prevent errors.`	`PAYMENT` sin `amount`.
`invoiceIds must be array of invoices`	`invoiceIds` no es un arreglo de ids `in_…`.
`either expirationDate or paymentMethodId must be set`	`PAYMENT` sin `expirationDate`.
`paymentInstrumentId is not valid`	El id no cumple el formato `pin_…`.
`expirationDate must be set with paymentInstrumentId`	Pago con tarjeta guardada sin vencimiento.
`paymentInstrumentId and a visible PAN iframe (panDivId) cannot be used together`	El constructor tiene `panDivId` y se envió `paymentInstrumentId`.
`either paymentInstrumentId, paymentMethodId or a visible PAN iframe (panDivId) must be set`	No hay de dónde obtener el número de tarjeta.
`subscriptionId must be set` / `expirationDate must be set` / `tokuProducts must be set`	`INSCRIPTION` sin el campo.