Saltar al contenido principal
Los secure fields son entradas de tarjeta que cumplen PCI (número de tarjeta, vencimiento, CVV) que el SDK renderiza dentro de iframes aislados. A diferencia del formulario integrado del SDK, creas y colocas cada campo de forma independiente en tu propio diseño, con tus propias etiquetas y estilos. Los datos sin procesar de la tarjeta nunca tocan tu página.
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.
Los secure fields funcionan tanto para el pago (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. Proporciona createPayment en la configuración para hacer POST del token desde tu propio backend:
Lee siempre token.checkout_session del token en lugar de reutilizar la sesión con la que creaste la transacción. Después de un pago rechazado, el SDK rota la sesión automáticamente. El token siempre lleva la sesión contra la que realmente tokenizó.
En ambos casos, el SDK gestiona 3DS e informa mediante 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:
  1. La sesión de checkout se clona en el servidor y se rota hacia los campos montados automáticamente.
  2. Los errores a nivel de campo (número de tarjeta inválido, CVV inválido, fondos insuficientes) se muestran dentro de los iframes correspondientes.
  3. En modo manual (createPayment en la configuración), onStatus recibe el resultado DECLINED / ERROR para que tu página pueda volver a habilitar su botón de pago. En modo administrado, el SDK no llama a onStatus para ese intento. El comprador ve los errores de los campos y puede enviar de nuevo.
Un rechazo que no permite reintentar llega a 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 una customerSession, 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:
Pasa la opción en la primera llamada a 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

Pasa options a create para etiquetar, estilizar y observar un campo.

Métodos de los campos

Cada campo devuelto por create (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 un generateToken ni un continuePayment() 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 getPaymentMethodsViews pueden compartir la página y la transacción: un start() de CARD se dirige a tus campos, y los botones de billetera funcionan por sí solos.