Métodos de pago (PIX, boleto, Apple Pay, Google Pay)

Una sola instancia del Bridge SDK cubre todos los métodos de pago que tu Merchant tiene habilitados. Cards, PIX, boleto, Apple Pay y Google Pay comparten el mismo flujo: el cliente paga en el navegador, el SDK devuelve una referencia de token de corta duración y solo reenvías esa referencia a tu backend para realizar el cobro. Las tarjetas y las wallets devuelven un tok_…; PIX y boleto devuelven un token de pagador (ptk_…) que contiene los datos del pagador.

Esta página documenta los módulos de PIX, boleto, Apple Pay y Google Pay. Para la recolección de tarjetas, consulta Tokenización y la Guía rápida del SDK.

Cómo encaja todo

Cada método produce el mismo tipo de referencia de token. El navegador nunca conserva las credenciales de pago en bruto, y el cobro real ocurre del lado del servidor con tu clave secreta.

Descubre los métodos habilitados

Qué métodos están disponibles depende de lo que el Merchant haya habilitado en el Tokeflow Dashboard durante la incorporación. Léelos en tiempo de ejecución en lugar de codificar de forma fija una interfaz de pago.

Llama a tokeflow.getAvailablePaymentMethods() (válido después de init()), o usa el hook de React useAvailablePaymentMethods(). Devuelve un subconjunto de 'cards', 'pix', 'boleto', 'applePay' y 'googlePay'.

await tokeflow.init();

const methods = tokeflow.getAvailablePaymentMethods();
// e.g. ['cards', 'pix', 'applePay']

if (methods.includes('pix')) {
  // render the PIX flow
}

import { useAvailablePaymentMethods } from '@tokeflow_com/bridge-js/react';

function PaymentOptions() {
  const methods = useAvailablePaymentMethods();
  return (
    <>
      {methods.includes('pix') && <PixForm />}
      {methods.includes('boleto') && <BoletoForm />}
      {methods.includes('applePay') && <ApplePayButton />}
      {methods.includes('googlePay') && <GooglePayButton />}
    </>
  );
}

PIX (Brasil)

PIX es el método de pago instantáneo de Brasil. El Bridge SDK registra al pagador — nombre, correo electrónico y CPF o CNPJ — y devuelve un token de pagador (ptk_…). Tu servidor lo cobra con payer_token_id, de modo que nunca maneja el documento del pagador.

Crea un elemento CPF y luego llama a tokeflow.pix.tokenize(). name, email y phone pueden ser elementos de texto seguros o cadenas simples.

const cpfElement = tokeflow.createCpfElement();
cpfElement.mount('#cpf-element');

const token = await tokeflow.pix.tokenize({
  cpf: cpfElement,             // or `document`: a CPF or CNPJ
  name: 'João Silva',          // element or string
  email: 'joao@example.com',   // required
  phone: '+5511999990000',     // optional
});

// Send token.tokenId to YOUR server to create the charge.
await fetch('/api/payments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tokenId: token.tokenId }),
});

El SDK comprueba los dígitos de control del CPF/CNPJ antes de la solicitud (incluidos los CNPJ alfanuméricos); Tokeflow vuelve a comprobar cada campo.

La respuesta PixToken

tokeflow.pix.tokenize() se resuelve en un PixToken. El único campo que reenvías es tokenId; el resto son metadatos de visualización no sensibles.

// {
//   tokenId: 'ptk_a1b2c3d4e5',  // the reference you send to your server
//   type: 'pix',
//   documentType: 'cpf',
//   documentLastDigits: '25',
//   expiresAt: '2026-10-26T12:30:00.000Z'
// }

Boleto (Brasil)

Un boleto es un comprobante bancario que el cliente paga mediante su línea digitable o su código de barras, normalmente en unos pocos días. getAvailablePaymentMethods() solo incluye boleto cuando un conector al que el merchant enruta el boleto puede cobrarlo; de lo contrario, boleto.tokenize() lanza PAYMENT_METHOD_DISABLED.

tokeflow.boleto.tokenize() registra al pagador y devuelve un token de pagador. Un boleto también necesita la dirección de facturación. Cada campo puede ser un elemento seguro o una cadena simple.

const token = await tokeflow.boleto.tokenize({
  document: cpfElement,        // CPF or CNPJ; documentType inferred from length
  name: 'João Silva',
  email: 'joao@example.com',
  address: {
    street: 'Av. Paulista',
    number: '1000',            // optional
    complement: 'Apto 42',     // optional
    neighborhood: 'Bela Vista',
    city: 'São Paulo',
    state: 'SP',
    postalCode: '01310-100',
  },
});
// { tokenId: 'ptk_…', type: 'boleto', documentType: 'cpf', documentLastDigits: '25', expiresAt: '…' }

El SDK comprueba el CPF/CNPJ, el CEP y la UF antes de la solicitud. Un error de campo lanza VALIDATION_ERROR — o INVALID_DOCUMENT para el CPF/CNPJ — y error.details.fields asigna a cada campo que falla (por ejemplo address.postalCode) sus mensajes.

Cobrar un token de PIX o boleto

Tu servidor crea la transacción con el token como payer_token_id y devuelve payment_instructions al navegador:

const res = await fetch('https://api.tokeflow.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKEFLOW_SECRET_KEY}`,
    'Content-Type': 'application/json',
    // A retry with the same key replays the charge instead of spending a new token.
    'Idempotency-Key': `order_123-${tokenId}`,
  },
  body: JSON.stringify({
    payment_method: 'boleto',     // or 'pix'
    charge_type: 'payment',
    country: 'BR',
    amount: 10000,
    currency: 'BRL',
    external_order_id: 'order_123',
    payer_token_id: tokenId,
  }),
});
const { data } = await res.json();
// data.payment_instructions → return it to the browser

Un token de pagador es de un solo uso — un cargo fallido también lo consume — y, cuando se recoge dentro de una sesión de checkout, solo puede cobrarse con ese checkout_session_id. Un token inutilizable se rechaza con 400 INVALID_PAYER_TOKEN y no se cobra nada. El correo electrónico del token no vincula por sí solo el cargo a un cliente existente: envía customer_id, o el mismo correo desde tu servidor. Reglas completas: Pagadores de PIX y boleto.

Para mostrar el resultado, renderiza qr_code_text (copia e cola) y qr_code_url para PIX. Para un boleto, el componente de React <BoletoInstructions> renderiza la línea digitable, un botón de copiar, la fecha de vencimiento y un enlace al boleto.

Apple Pay

El módulo de Apple Pay presenta la hoja nativa de Apple Pay, captura el pago autorizado en el navegador y lo intercambia por una referencia de token de wallet. Apple Pay solo está disponible en dispositivos y navegadores Apple compatibles.

Configurar

Configura el módulo una sola vez después de init(). El importe en la solicitud de pago se expresa como una cadena decimal, tal como Apple Pay lo espera.

tokeflow.applePay.configure({
  merchantId: 'merchant.com.yourcompany',
  merchantName: 'Your Company',
  countryCode: 'US',
  currencyCode: 'USD',
});

Comprueba la disponibilidad e inicia el pago

Condiciona el botón de Apple Pay a isSupported() (el navegador es compatible con Apple Pay) y canMakePayments() (el dispositivo tiene una tarjeta utilizable). Cuando el cliente toca el botón, llama a beginPayment() con una solicitud de pago y un conjunto de callbacks. En onAuthorized, tokeniza el pago autorizado y reenvía la referencia de token a tu servidor.

if (tokeflow.applePay.isSupported() && (await tokeflow.applePay.canMakePayments())) {
  tokeflow.applePay.beginPayment(
    { total: { label: 'Total', amount: '10.00' } },
    {
      onAuthorized: async ({ payment }) => {
        const token = await tokeflow.applePay.tokenize(payment);

        // Send token.tokenId to YOUR server to create the charge.
        await fetch('/api/payments', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ tokenId: token.tokenId }),
        });
      },
      onCancel: () => {},
      onError: (err) => console.error(err),
    }
  );
}

El elemento de botón

Puedes renderizar un botón prediseñado y compatible con Apple en lugar de estilizar el tuyo propio:

const button = tokeflow.createApplePayButton();
button.mount('#apple-pay-button');

En React, usa el componente <ApplePayButton>.

Métodos de Apple Pay

Google Pay

El módulo de Google Pay carga la hoja de pago de Google Pay, captura los datos de pago seleccionados y los intercambia por una referencia de token de wallet.

Configurar

tokeflow.googlePay.configure({
  merchantId: 'your-merchant-id',
  merchantName: 'Your Company',
});

Comprueba la disponibilidad y carga los datos de pago

Condiciona el botón de Google Pay a isSupported() (el navegador es compatible con Google Pay) e isReadyToPay() (el cliente tiene un método de pago utilizable). Cuando el cliente toca el botón, llama a loadPaymentData() con una solicitud de pago y luego tokeniza los datos de pago devueltos.

if (tokeflow.googlePay.isSupported() && (await tokeflow.googlePay.isReadyToPay())) {
  const paymentData = await tokeflow.googlePay.loadPaymentData(request);
  const token = await tokeflow.googlePay.tokenize(paymentData);

  // Send token.tokenId to YOUR server to create the charge.
  await fetch('/api/payments', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ tokenId: token.tokenId }),
  });
}

El elemento de botón

const button = tokeflow.createGooglePayButton();
button.mount('#google-pay-button');

En React, usa el componente <GooglePayButton>.

Métodos de Google Pay

Cobra el token desde tu servidor

Sea cual sea el método, el resultado es una referencia tok_…. Tu backend crea la transacción con tu clave secreta, haciendo referencia al token, y envía una Idempotency-Key para que un reintento nunca cobre dos veces. Establece payment_method para que coincida con el método que usó el cliente (pix, wallet o credit_card).

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_2026_0623_attempt_1" \
  -d '{
    "customer_id": "cust_a1b2c3d4e5",
    "amount": 15000,
    "currency": "BRL",
    "payment_method": "pix",
    "charge_type": "payment",
    "country": "BR",
    "card_ciphertext_id": "tok_a1b2c3d4e5"
  }'

La respuesta de éxito viene envuelta en el sobre estándar:

{
  "success": true,
  "data": {
    "id": "tx_9f8e7d6c5b",
    "status": "pending",
    "amount": 15000,
    "currency": "BRL",
    "payment_method": "pix",
    "charge_type": "payment",
    "country": "BR",
    "customer_id": "cust_a1b2c3d4e5",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c2a1b",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

El flujo completo de cobro — captura, reembolsos y la línea de tiempo de intentos — se encuentra en Transacciones.

Próximos pasos

• Descripción general del Bridge SDK — elementos, wallets, contexto de checkout y el modelo de configuración completo.
• Tokenización — formas de entrada de tokenización, opciones y la respuesta del token.
• Elementos — todos los elementos de entrada, incluido el elemento CPF utilizado para PIX.
• Transacciones — cobra el token, luego captura, anula o reembolsa.