Esta es la API granular por campo, solo para Web. Si prefieres que el SDK renderice su propio formulario de tarjeta prediseñado en lugar de armar cada entrada tú mismo, usa la Lista de métodos de pago: el SDK compone y renderiza el formulario en tu
elementSelector, con las mismas garantías PCI y menos trabajo de diseño.checkoutSession) como para la inscripción (customerSession). Los campos heredan todo (sesión, país, idioma, callbacks) del Transaction que los crea. No hay una segunda superficie de configuración.
Inicio rápido
start() tokeniza los campos montados, crea el pago, gestiona 3DS e informa el resultado mediante onStatus. Los campos aportan el número de tarjeta, el vencimiento y el CVV. Estos nunca salen de los iframes. Los detalles que no son PCI (holderName y, opcionalmente, installment, customer o vaultOnSuccess) viajan en start() mediante paymentMethod.data.
Pasar
number, expirationMonth, expirationYear o securityCode en paymentMethod.data.card mientras hay secure fields montados genera un error: los iframes son dueños de los datos PCI.Administrado vs manual
De forma predeterminada, el SDK crea el pago. ProporcionacreatePayment en la configuración para hacer POST del token desde tu propio backend:
onStatus.
Pagos rechazados y reintento
Cuando un pago con tarjeta es DECLINED o falla con ERROR y la respuesta permite reintentar, el SDK prepara el reintento por ti:- La sesión de checkout se clona en el servidor y se rota hacia los campos montados automáticamente.
- Los errores a nivel de campo (número de tarjeta inválido, CVV inválido, fondos insuficientes) se muestran dentro de los iframes correspondientes.
- En modo manual (
createPaymenten la configuración),onStatusrecibe el resultadoDECLINED/ERRORpara que tu página pueda volver a habilitar su botón de pago. En modo administrado, el SDK no llama aonStatuspara ese intento. El comprador ve los errores de los campos y puede enviar de nuevo.
onStatus en ambos modos y cierra la sesión de checkout.
Los campos permanecen montados con lo que escribió el usuario. Para reintentar, simplemente llama a start() de nuevo: es repetible mientras haya secure fields montados, y el nuevo intento tokeniza contra la sesión rotada. No tienes que gestionar la sesión.
Una vez que el pago es final (aprobado, o rechazado sin reintento), la sesión de checkout se cierra y start() genera un error. Para cobrar otro pago, crea una nueva sesión de checkout en tu backend y llama a transaction.updateCheckoutSession(newSession). Los campos montados la toman y start() vuelve a funcionar.
Vuelve a habilitar tu botón de pago cuando la promesa de start() se resuelva. Funciona en ambos modos:
Deshabilita tu botón de pago mientras un
start() está en curso. Llamar a start() de nuevo antes de que termine el intento anterior genera un error: dos tokenizaciones significarían dos pagos.Inscripción
Con unacustomerSession, los secure fields guardan una tarjeta en el vault en lugar de cobrarla. El flujo es idéntico: create, mount, start().
Cuotas
Habilita las cuotas al crear los campos:secureFields(). La transacción mantiene una sola instancia de secure fields. Las llamadas posteriores la devuelven, y una llamada con un installmentEnable distinto genera un error. Para cambiar la opción, llama a transaction.unmount() y crea los campos de nuevo.
Los planes disponibles llegan en el onChange del campo pan mientras el usuario escribe: data.installments, data.fullInstallmentsInfo y data.isInstallmentLoading. Renderiza tu propio selector a partir de esos datos y pasa el plan elegido en start():
Campos
Crea cada campo por nombre y luego móntalo en cualquier elemento de tu diseño.Opciones de los campos
Pasaoptions a create para etiquetar, estilizar y observar un campo.
Métodos de los campos
Cada campo devuelto porcreate (o recuperado después con getElement({ name })) expone:
Miembros de la instancia
Para apuntar la transacción a una nueva sesión de checkout, llama a
transaction.updateCheckoutSession(): los campos montados la toman automáticamente.Notas
- Una sola ruta de finalización. La tokenización, la creación del pago, 3DS y el estado ocurren dentro de
start(): no hay ungenerateTokenni uncontinuePayment()que debas secuenciar tú. Para crear el pago desde tu propio backend, usa el modo manual (createPayment). El SDK sigue encargándose de 3DS y del resultado. - El alcance de PCI no cambia. Los datos sin procesar de la tarjeta permanecen dentro de los iframes del SDK; tu código nunca los lee.
- Una superficie de tarjeta por página. Crea secure fields en una transacción a la vez. Los botones de billetera y la lista de métodos de pago de
getPaymentMethodsViewspueden compartir la página y la transacción: unstart()deCARDse dirige a tus campos, y los botones de billetera funcionan por sí solos.
Relacionado
- Migración: Secure Fields. Si vienes de
yuno.secureFieldsv1. - Lista de métodos de pago. Widgets prediseñados: billeteras y la lista de métodos.
createPayment. Toma el control de la creación del pago (modo manual).onStatus. Recibe el resultado final.