Usa una única integración para aceptar pagos a través de botones de pago con un clic. El componente Express Checkout es una funcionalidad del SDK de Fintoc que permite a tus clientes pagar con botones de wallet, sin abrir el widget completo. El método de pago soportado actualmente es Apple Pay. Los clientes ven el botón de Apple Pay según su dispositivo y navegador. Si Apple Pay no está disponible en el dispositivo, el botón queda oculto.

Antes de comenzar: tu dominio debe estar habilitado para Apple Pay. Apple Pay no se cargará hasta que Fintoc registre tu dominio con Apple, por lo que el botón permanecerá oculto en un dominio no registrado. Consulta Habilitar Apple Pay para iniciar el proceso antes de integrar.

Aceptar pagos con Apple Pay usando Express Checkout requiere seis pasos:

Configura tu servidor para crear un Checkout Session
Configura el SDK de Fintoc en tu frontend
Crea y monta el componente Express Checkout
Maneja el callback onPaymentRequest
Envía el pago a Fintoc
Prueba la integración

Paso 1: Configura tu servidor

Lado del servidor

Express Checkout llama al callback onPaymentRequest después de que el cliente autoriza la hoja de Apple Pay. En ese callback debes crear una Checkout Session desde tu backend y devolver su session_token al navegador. Expone un endpoint en tu servidor que cree una Checkout Session con la API de Fintoc: Node

// server.js (Node example)
app.post("/api/create-checkout", async (req, res) => {
  const response = await fetch("https://api.fintoc.com/v2/checkout_sessions", {
    method: "POST",
    headers: {
      Authorization: process.env.FINTOC_SECRET_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 1000,
      currency: "CLP",
      payment_methods: ["card"],
      recipient_account: { id: "acc_a1b2c3d4e5" },
      // ...any other fields your flow requires
    }),
  });

  const session = await response.json();
  res.json({ session_token: session.session_token });
});

Nunca expongas tu secret key en el navegador. Siempre mantén la llamada de creación de Checkout Session en tu servidor.

Paso 2: Configura el SDK de Fintoc

Lado del cliente

Express Checkout está disponible automáticamente como una funcionalidad del SDK de Fintoc. Incluye el script de Fintoc en tu página de checkout agregándolo al <head> de tu archivo HTML. Siempre carga el SDK directamente desde js.fintoc.com para recibir actualizaciones de seguridad. No incluyas el script en un bundle ni hospedes una copia por tu cuenta.

<head>
  <title>Checkout</title>
  <script src="https://js.fintoc.com/v1/"></script>
</head>

Paso 3: Crea y monta el Express Checkout

Lado del cliente

El componente Express Checkout renderiza el botón de wallet dentro de un iframe que envía de manera segura la información de pago a Fintoc a través de una conexión HTTPS. La dirección de la página de checkout también debe comenzar con https://, no con http://, para que tu integración funcione. Primero, crea un nodo DOM vacío (contenedor) con un ID único en tu formulario de pago:

<div id="apple-pay-container">
  <!-- Express Checkout will be inserted here -->
</div>
<div id="error-message">
  <!-- Display an error message to your customers here -->
</div>

Cuando el formulario se haya cargado, crea una instancia del widget y monta Express Checkout en el nodo DOM contenedor:

const widget = window.Fintoc.create({
  product: "payments",
  publicKey: "pk_test_...",
  country: "cl",

  expressCheckout: {
    container: "apple-pay-container",
    amount: 1000,
    currency: "CLP",
  },

  onPaymentRequest: async ({ payment_method_type, wallet }) => {
    const res = await fetch("/api/create-checkout", { method: "POST" });
    const { session_token } = await res.json();
    return { sessionToken: session_token };
  },

  onSuccess: (data) => console.log("Payment succeeded", data),
  onExit: (reason) => console.log("Widget closed", reason),
  onEvent: (eventName, metadata) => console.log(eventName, metadata),
});

Los botones de Apple Pay pueden tener los siguientes estilos:

Paso 4: Maneja el callback onPaymentRequest

Lado del cliente

onPaymentRequest se ejecuta cuando el SDK necesita un sessionToken para continuar con el flujo. Para Apple Pay, el SDK lo llama después de que el cliente autoriza la hoja de Apple Pay. Cuando llamas a widget.open() para transferencia bancaria, el SDK llama al mismo callback antes de abrir el widget. En ese callback debes llamar a tu servidor, obtener un session_token y devolverlo al SDK. El callback recibe un único argumento con información sobre el método solicitado:

Campo	Tipo	Descripción
`payment_method_type`	`string`	`"card"` para pagos con wallet. `"bank_transfer"` cuando se llama a `widget.open()`.
`wallet`	`string` (opcional)	La wallet específica seleccionada, por ejemplo `"apple_pay"`. `undefined` para transferencia bancaria.

Tu callback debe resolverse con { sessionToken: string } en un máximo de 30 segundos, o el SDK emite payment_error.

Puedes usar los campos payment_method_type y wallet para reutilizar un único endpoint tanto para wallets como para transferencia bancaria, o para enrutar a diferentes endpoints si la lógica de tu backend difiere.

Paso 5: Envía el pago a Fintoc

Lado del cliente

Una vez que el cliente autoriza el pago con wallet, el SDK completa automáticamente el flujo. No necesitas llamar a un método confirmPayment por tu cuenta. La secuencia es:

El SDK abre la hoja de Apple Pay y solicita un token de pago a Apple Pay.
Una vez que el cliente autoriza, el SDK emite processing_express_checkout_payment.
El SDK llama a tu callback onPaymentRequest para obtener un sessionToken fresco.
El SDK envía ambos tokens al backend de Fintoc, que crea el Payment Resource y cobra a la wallet.
Cuando el pago alcanza status === 'succeeded', el SDK llama a onSuccess(data) con el recurso resultante.

Si el estado del pago es distinto de succeeded, o cualquier paso del flujo falla, el SDK emite payment_error en lugar de llamar a onSuccess.

Manejo del estado de carga durante el procesamiento del pago

Mientras Express Checkout procesa un pago, debes mostrar un estado de carga para dar retroalimentación clara a tu cliente y evitar interacciones duplicadas. Manéjalo desde los callbacks onEvent y onSuccess que ya pasas a Fintoc.create:

processing_express_checkout_payment se dispara una vez que el cliente autoriza el pago. Úsalo para mostrar tu indicador de carga mientras el SDK obtiene un sessionToken fresco desde tu servidor y envía el pago.
El pago luego se resuelve a través de onSuccess cuando es exitoso, o a través de un evento payment_error cuando falla. Usa ambos para limpiar el indicador de carga.

Una implementación típica se ve así:

window.Fintoc.create({
  // ...
  onEvent: (eventName) => {
    if (eventName === "processing_express_checkout_payment") {
      // Show loading state (e.g. spinner, disable buttons)
      setLoading(true);
    }
    if (eventName === "payment_error") {
      // Hide loading state after a failed attempt
      setLoading(false);
    }
  },
  onSuccess: () => {
    // Hide loading state after a successful payment
    setLoading(false);
  },
});

Siempre limpia el estado de carga tanto en onSuccess como en payment_error para que la UI nunca quede atascada después de un intento de pago.

Paso 6: Prueba la integración

Antes de pasar a producción, prueba la integración en un dispositivo que soporte Apple Pay. Requisitos para probar:

Usa tu public key de prueba y una cuenta de destinatario de prueba.
Abre tu checkout en iOS o macOS.
Asegúrate de que tu dominio de staging esté habilitado para Apple Pay. Si aún no lo has hecho, sigue Habilitar Apple Pay primero.

Checklist de integración:

El botón de Apple Pay se renderiza al cargar la página en un dispositivo soportado.
express_checkout_ready se dispara con wallets.applePay === true.
Autorizar la hoja de Apple Pay dispara onPaymentRequest con payment_method_type: 'card', wallet: 'apple_pay'.
processing_express_checkout_payment se dispara mientras el pago está en curso.
onSuccess se dispara con el recurso de pago después de una autorización exitosa.
Cancelar la hoja de Apple Pay no emite payment_error.
Llamar a widget.open() (fallback de transferencia bancaria) invoca onPaymentRequest con payment_method_type: 'bank_transfer' y abre el widget.

Configuraciones opcionales

Escuchar el evento express_checkout_ready

Después del montaje, Express Checkout no mostrará botones hasta que el SDK se inicialice y verifique la disponibilidad de wallets. Para animar el elemento cuando aparezca el botón, escucha el evento express_checkout_ready. Inspecciona el valor wallets para determinar qué botones mostrar, si los hay:

// Optional: hide the element until we know if a button will show
const container = document.getElementById("apple-pay-container");
container.style.visibility = "hidden";

window.Fintoc.create({
  // ...
  onEvent: (eventName, metadata) => {
    if (eventName === "express_checkout_ready") {
      if (metadata.wallets.applePay) {
        container.style.visibility = "initial";
      } else {
        // No buttons will show; fall back to bank transfer only
      }
    }
  },
});

Estilizar el botón

Puedes ajustar la apariencia del botón de Apple Pay a través de los campos opcionales de expressCheckout.

expressCheckout: {
  container: "apple-pay-container",
  amount: 1000,
  currency: "CLP",

  // Height in pixels. Defaults to 44. Range [40, 100].
  buttonHeight: 52,
  // Border radius in pixels. Defaults to 4. Range [0, 100].
  buttonBorderRadius: 12,
  // Specify the label shown inside the button.
  // Defaults to "plain" for Apple Pay.
  buttonType: { applePay: "buy" },
  // Specify the color scheme of the button.
  // Defaults to "black".
  buttonStyle: { applePay: "white" },
  // Specify the language for the Apple Pay label.
  // Defaults to "es-ES".
  locale: { applePay: "es-MX" },
}

Opción	Tipo	Default	Descripción
`buttonHeight`	`number` (px)	`44`	Altura del botón. Acotado a `[40, 100]`.
`buttonBorderRadius`	`number` (px)	`4`	Radio del borde del botón. Acotado a `[0, 100]`.
`buttonType.applePay`	`"buy"`, `"pay"`, o `"plain"`	`"plain"`	Etiqueta mostrada dentro del botón de Apple Pay.
`buttonStyle.applePay`	`"black"` o `"white"`	`"black"`	Esquema de color del botón de Apple Pay.
`locale.applePay`	`"es-ES"` o `"es-MX"`	`"es-ES"`	Idioma para la etiqueta del botón de Apple Pay.

Los valores fuera del rango permitido se acotan en lugar de rechazarse. Por ejemplo, buttonHeight: 200 se trata como 100.

El mismo objeto widget devuelto por Fintoc.create expone los métodos habituales del widget. Cuando expressCheckout está configurado, llamar a widget.open() invoca automáticamente onPaymentRequest con payment_method_type: 'bank_transfer' antes de abrir el widget, por lo que no necesitas una segunda inicialización.

document
  .getElementById("bank-transfer-button")
  .addEventListener("click", () => widget.open());

Referencia de eventos

Express Checkout usa el mismo callback onEvent que el resto del widget (referencia de eventos del widget), además de los eventos específicos de este componente:

Evento	Payload	Cuándo se dispara
`express_checkout_ready`	`{ wallets: { applePay?: boolean } }`	Una vez que el SDK termina de inicializarse. El objeto `wallets` lista las wallets que se renderizaron exitosamente. Si está vacío, ninguna está disponible, por ejemplo en un navegador no soportado o un dominio no verificado.
`processing_express_checkout_payment`	None	Después de que el cliente confirma el pago con wallet y el SDK está intercambiando tokens con tu servidor y el backend de Fintoc.
`payment_error`	None	El pago con wallet falló en algún paso: `onPaymentRequest` rechazó o expiró por tiempo, el proveedor de wallet devolvió un error, o el estado del pago resultante no es `succeeded`.
`express_checkout_error`	None	Un error interno impidió que el botón se renderizara, por ejemplo cuando el SDK falla al cargar o el contenedor no se encuentra.

Referencia completa de opciones

Fintoc.create(options)

Parámetro	Tipo	Requerido	Descripción
`product`	`"payments"`	Sí	Valor literal `"payments"` para Express Checkout.
`publicKey`	`string`	Sí	Tu publishable key.
`country`	`"cl"` o `"mx"`	No	País de destino. Por defecto `"cl"`.
`expressCheckout`	`ExpressCheckoutConfig`	Sí	Configuración para el botón de wallet.
`onPaymentRequest`	`(data) => Promise<{ sessionToken }>`	Sí	Callback que devuelve un `sessionToken` cuando el SDK necesita uno para continuar el flujo.
`onSuccess`	`(data) => void`	No	Callback que recibe el recurso de pago una vez que el pago alcanza `succeeded`.
`onExit`	`(reason?: string) => void`	No	Callback que se ejecuta cuando el widget se cierra.
`onEvent`	`(eventName, metadata?) => void`	No	Callback que recibe cada evento del widget.

ExpressCheckoutConfig

Parámetro	Tipo	Requerido	Descripción
`container`	`string`	Sí	`id` del elemento DOM donde el SDK renderiza el botón de wallet.
`amount`	`number`	Sí	Monto a cobrar, en la unidad menor de la moneda. Por ejemplo, CLP no tiene decimales y MXN usa centavos.
`currency`	`string`	Sí	Código ISO 4217 de tres letras de la moneda, por ejemplo `"CLP"` o `"MXN"`.
`buttonHeight`	`number`	No	Altura del botón en px. Rango `[40, 100]`. Default `44`.
`buttonBorderRadius`	`number`	No	Radio del borde del botón en px. Rango `[0, 100]`. Default `4`.
`buttonType.applePay`	`"buy"`, `"pay"`, o `"plain"`	No	Etiqueta del botón de Apple Pay. Default `"plain"`.
`buttonStyle.applePay`	`"black"` o `"white"`	No	Esquema de color de Apple Pay. Default `"black"`.
`locale.applePay`	`"es-ES"` o `"es-MX"`	No	Idioma del botón de Apple Pay. Default `"es-ES"`.

Habilitar Apple Pay

Apple Pay no se cargará en un dominio hasta que Fintoc lo haya registrado con Apple. El registro es un prerrequisito tanto para pruebas como para producción. Completa el registro para cada dominio que mostrará el botón, tanto en staging como en producción. Cada dominio registrado debe usar HTTPS. El proceso funciona así:

Avisa a Fintoc que quieres usar Apple Pay. Contacta a tu account manager, contacto de customer success, o contacto de ventas, y comparte los dominios que planeas integrar.
Hospeda el archivo de verificación que Fintoc te envía. Fintoc te envía un archivo de asociación de dominio. Hospédalo en cada dominio bajo la ruta /.well-known/apple-developer-merchantid-domain-association, de modo que sea accesible en https://your-domain.com/.well-known/apple-developer-merchantid-domain-association. El archivo debe devolver 200 OK y ser descargable.
Confirma que el archivo está activo. Avísale a Fintoc una vez que el archivo esté hospedado en cada dominio. Fintoc luego registra cada dominio con Apple.
Prueba tu integración. Una vez que tus dominios estén registrados, el botón de Apple Pay puede cargarse y puedes seguir los pasos de prueba en un dispositivo soportado.

Si un dominio no está registrado, el botón de Apple Pay permanecerá oculto y express_checkout_ready reporta que no hay wallet de Apple Pay disponible (wallets.applePay no es true). Confirma que el dominio esté habilitado antes de depurar tu integración.

Ver también

Aceptar un pago: guía estándar de integración de Checkout Session.
Integración Web: guía completa de integración del widget.
Escuchar eventos del Widget: catálogo completo de eventos.
Integración WebView: integrar el widget dentro de una app nativa.

Inicio

Recursos

Pagos

Transferencias

Movimientos

Aceptar un pago con un clic usando Apple Pay

Paso 1: Configura tu servidor

Paso 2: Configura el SDK de Fintoc

Paso 3: Crea y monta el Express Checkout

Paso 4: Maneja el callback onPaymentRequest

Paso 5: Envía el pago a Fintoc

Manejo del estado de carga durante el procesamiento del pago

Paso 6: Prueba la integración

Configuraciones opcionales

Escuchar el evento express_checkout_ready

Estilizar el botón

Referencia de eventos

Referencia completa de opciones

Fintoc.create(options)

ExpressCheckoutConfig

Habilitar Apple Pay

Ver también

​Paso 1: Configura tu servidor

​Paso 2: Configura el SDK de Fintoc

​Paso 3: Crea y monta el Express Checkout

​Paso 4: Maneja el callback onPaymentRequest

​Paso 5: Envía el pago a Fintoc

​Manejo del estado de carga durante el procesamiento del pago

​Paso 6: Prueba la integración

​Configuraciones opcionales

​Escuchar el evento express_checkout_ready

​Estilizar el botón

​Referencia de eventos

​Referencia completa de opciones

​Fintoc.create(options)

​ExpressCheckoutConfig

​Habilitar Apple Pay

​Ver también

Paso 1: Configura tu servidor

Paso 2: Configura el SDK de Fintoc

Paso 3: Crea y monta el Express Checkout

Paso 4: Maneja el callback onPaymentRequest

Paso 5: Envía el pago a Fintoc

Manejo del estado de carga durante el procesamiento del pago

Paso 6: Prueba la integración

Configuraciones opcionales

Escuchar el evento express_checkout_ready

Estilizar el botón

Referencia de eventos

Referencia completa de opciones

Fintoc.create(options)

ExpressCheckoutConfig

Habilitar Apple Pay

Ver también