Widget de checkout: configuración de un formulario de pago drop-in seguro para PCI

El Widget de checkout es un formulario de pago totalmente renderizado y seguro para PCI que insertas en tu página. Maneja los inputs de tarjeta, la visualización de tarjetas guardadas y la casilla de consentimiento “Guardar esta tarjeta” — sin que construyas ningún HTML de formulario. Si quieres control total sobre el diseño y el estilo, usa los Campos alojados en su lugar.

Configuración básica

Llama a sdk.checkout() después de inicializar el SDK. El widget se monta a sí mismo en el DOM automáticamente.

const checkout = sdk.checkout({
  shopperId: sdk.sessionData().customerId,
  vaultConsentEnabled: true,
  onSavedMethodSelected: (token) => {
    // Un comprador recurrente eligió una tarjeta guardada
    // Cóbrala directamente usando sdk.authorizeToken(token)
  },
})

Para montar el widget en un elemento específico, pasa un selector CSS:

const checkout = sdk.checkout({
  container: '#checkout-container',
  vaultConsentEnabled: true,
})

Idioma (`locale`)

Configura locale para elegir el idioma del texto integrado del widget: 'en', 'es' o 'pt'. Si lo omites, el widget usa el idioma del navegador del comprador y recurre al inglés cuando ese idioma no es compatible.

const checkout = sdk.checkout({
  locale: 'es',
})

locale cubre todo el texto propio del widget, no solo la casilla de consentimiento: los botones de pagar y suscribirse, el pie “Secured by Therius”, las etiquetas y marcadores de posición del formulario de tarjeta, el texto de tarjetas guardadas, los avisos de suscripción y de tarjeta en archivo, el texto de los paneles de Pix y Affirm, y los mensajes comunes de rechazo y error. El contenido de tu propia página y cualquier texto devuelto por un proveedor de pagos no se traducen.

Callbacks

Callback	Se dispara cuando
`onActionComplete(result)`	Un pago llega a un estado final después de una acción emergente (3DS o redirección) o después de la llamada de autorización integrada del widget. `result` contiene `status`, `paymentCode` y, en la ruta de reanudación, el `payment` completo. Úsalo para mostrar el resultado final en tu interfaz.
`onDeclined(info)`	Un pago es rechazado y el widget tiene una guía de recuperación. `info` contiene `reason` y `recoveryAction` (`'retry'`, `'switch_method'` o `'terminal'`). El widget ya muestra su propia interfaz de recuperación, así que úsalo solo para registrar o reportar el rechazo.
`onError(error)`	El widget encuentra un error que no es un rechazo.
`onMethodChange(method)`	El comprador cambia de pestaña de método de pago.

onNonce, onApm y onWalletToken son interceptores opcionales. Si los omites, el widget llama por sí mismo al método del SDK correspondiente y reporta el resultado mediante onActionComplete o onError. Proporciónalos solo si necesitas enrutar el pago a través de tu propio servidor.

Cuando autorizas desde tu propio servidor, envía la dirección IP real del comprador como ipAddress en la solicitud de pago. La dirección de tu servidor no es la del comprador, y la puntuación antifraude y algunos proveedores dependen de la real. El widget la obtiene por ti y la entrega a onNonce, onApm y onSavedMethodSelected como shopper.ipAddress (no está presente si la consulta falla):

onNonce: async (nonce, ddcSessionId, vaultConsent, shopper) => {
  await fetch('/pay', {
    method: 'POST',
    body: JSON.stringify({ nonce, ddcSessionId, ipAddress: shopper?.ipAddress }),
  })
}

Cuando el widget autoriza por sí mismo, Therius usa la dirección de la conexión del comprador, por lo que no necesitas hacer nada más.

Selector de tarjetas guardadas

Si la sesión se creó con un customerId y ese comprador tiene tarjetas previamente depositadas en el vault, el widget renderiza automáticamente un selector de tarjetas encima del formulario de tarjeta nueva. Las tarjetas se muestran como brand / last 4 / expiry — nunca se devuelve ningún PAN al navegador. Cuando el comprador selecciona una tarjeta guardada, onSavedMethodSelected se dispara con el token de la tarjeta. Cóbrala de inmediato sin un nonce:

const checkout = sdk.checkout({
  onSavedMethodSelected: async (token) => {
    const result = await sdk.authorizeToken(token, {
      amount: { currency: 'USD', value: 4999, exponent: 2 },
    })
    if (result.actionRequired) {
      const finalResult = await sdk.handleAction(result.actionRequired)
    }
  },
})

La lista de tarjetas guardadas está respaldada por GET /sdk/vaulted-methods y está limitada al propio comprador de la sesión — el navegador no puede enumerar las tarjetas de un comprador diferente.

Combina vaultConsentEnabled: true con un customerId en tu llamada a POST /sdk/session para la mejor experiencia de comprador recurrente. Cuando hay un shopperId presente en la sesión, la casilla “Guardar esta tarjeta” aparece automáticamente.

Para una tarjeta nueva ingresada a través del widget, recupera el nonce después de que el comprador envía el formulario y úsalo de la misma forma que con los campos alojados:

checkout.on('submit', async ({ nonce }) => {
  const result = await sdk.authorize(nonce)
  if (result.actionRequired) {
    const finalResult = await sdk.handleAction(result.actionRequired)
  }
})

Alternativamente, llama a sdk.authorize(nonce) directamente después del envío del widget para dejar que el SDK administre el ciclo completo de autorizar-y-acción en una sola llamada.

Manejo de 3DS

3DS se maneja de forma idéntica a los campos alojados. Si el resultado del cobro incluye actionRequired, pásalo a sdk.handleAction:

if (result.actionRequired) {
  const finalResult = await sdk.handleAction(result.actionRequired)
}

sdk.handleAction abre el iframe del desafío de 3DS, espera a que se complete y resuelve con el PaymentResult final. No necesitas escribir lógica separada para diferentes tipos de desafío.

vaultConsentEnabled solo muestra la casilla “Guardar esta tarjeta” cuando hay un shopperId presente en la sesión. Si no se pasó ningún customerId a POST /sdk/session, la casilla se oculta independientemente de este ajuste.

Si pasaste cardOnFile al crear la sesión (ver Suscripciones gestionadas por el comercio), el widget muestra un aviso fijo de “la tarjeta se guardará” en lugar de la casilla vaultConsentEnabled — la tarjeta se guarda incondicionalmente, así que no hay nada que aceptar.

Descripción general

Recolección de tarjeta

Billeteras y más

Widget de checkout: configuración de un formulario de pago drop-in seguro para PCI

Configuración básica

Idioma (`locale`)

Callbacks

Selector de tarjetas guardadas

Cobrar una tarjeta nueva desde el widget

Manejo de 3DS

​Configuración básica

​Idioma (locale)

​Callbacks

​Selector de tarjetas guardadas

​Cobrar una tarjeta nueva desde el widget

​Manejo de 3DS

Configuración básica

Idioma (`locale`)

Callbacks

Selector de tarjetas guardadas

Cobrar una tarjeta nueva desde el widget

Manejo de 3DS