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

Uma única instância do Bridge SDK cobre todos os métodos de pagamento que o seu Merchant tem habilitados. Cartões, PIX, boleto, Apple Pay e Google Pay compartilham o mesmo fluxo: o cliente paga no navegador, o SDK retorna uma referência de token de curta duração, e você encaminha apenas essa referência para o seu backend efetuar a cobrança. Cartões e carteiras retornam um tok_…; PIX e boleto retornam um token de pagador (ptk_…) que guarda os dados do pagador.

Esta página documenta os módulos de PIX, boleto, Apple Pay e Google Pay. Para a coleta de cartões, veja Tokenização e o início rápido do SDK.

Como tudo se encaixa

Todo método produz o mesmo tipo de referência de token. O navegador nunca retém credenciais de pagamento brutas, e a cobrança de fato acontece no lado do servidor com a sua chave secreta.

Descubra os métodos habilitados

Quais métodos estão disponíveis depende do que o Merchant habilitou no Tokeflow Dashboard durante o onboarding. Leia-os em tempo de execução em vez de fixar uma UI de pagamento no código.

Chame tokeflow.getAvailablePaymentMethods() (válido após init()), ou use o hook do React useAvailablePaymentMethods(). Ele retorna um subconjunto de 'cards', 'pix', 'boleto', 'applePay' e '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)

O PIX é o método de pagamento instantâneo do Brasil. O Bridge SDK registra o pagador — nome, e-mail e CPF ou CNPJ — e retorna um token de pagador (ptk_…). Seu servidor o cobra com payer_token_id, então ele nunca manipula o documento do pagador.

Crie um elemento de CPF e, em seguida, chame tokeflow.pix.tokenize(). name, email e phone podem ser elementos de texto seguros ou strings 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 }),
});

O SDK confere os dígitos verificadores do CPF/CNPJ antes da requisição (incluindo CNPJs alfanuméricos); a Tokeflow confere todos os campos novamente.

A resposta PixToken

tokeflow.pix.tokenize() resolve para um PixToken. O único campo que você envia adiante é o tokenId; o restante são metadados de exibição não sensíveis.

// {
//   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)

O boleto é um documento de cobrança bancária que o cliente paga pela linha digitável ou pelo código de barras, geralmente em poucos dias. boleto só é listado por getAvailablePaymentMethods() quando um conector para o qual o merchant roteia boleto consegue cobrar um; caso contrário, boleto.tokenize() lança PAYMENT_METHOD_DISABLED.

tokeflow.boleto.tokenize() registra o pagador e retorna um token de pagador. O boleto também precisa do endereço de cobrança. Cada campo pode ser um elemento seguro ou uma string simples.

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: '…' }

O SDK confere o CPF/CNPJ, o CEP e a UF antes da requisição. Um erro de campo lança VALIDATION_ERROR — ou INVALID_DOCUMENT para o CPF/CNPJ — e error.details.fields associa cada campo com falha (por exemplo address.postalCode) às suas mensagens.

Cobre um token de PIX ou boleto

Seu servidor cria a transação com o token como payer_token_id e devolve payment_instructions ao 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

Um token de pagador é de uso único — uma cobrança que falha também o consome — e, quando coletado dentro de uma sessão de checkout, só pode ser cobrado com aquele checkout_session_id. Um token inutilizável é recusado com 400 INVALID_PAYER_TOKEN e nada é cobrado. O e-mail do token, por si só, não vincula a cobrança a um cliente existente: envie customer_id, ou o mesmo e-mail a partir do seu servidor. Regras completas: Pagadores de PIX e boleto.

Para exibir o resultado no PIX, renderize qr_code_text (copia e cola) e qr_code_url. Para boleto, o componente React <BoletoInstructions> renderiza a linha digitável, um botão de copiar, a data de vencimento e um link para o boleto.

Apple Pay

O módulo Apple Pay apresenta a folha nativa do Apple Pay, captura o pagamento autorizado no navegador e o troca por uma referência de token de carteira. O Apple Pay está disponível apenas em dispositivos e navegadores Apple compatíveis.

Configurar

Configure o módulo uma única vez após init(). O valor monetário na solicitação de pagamento é expresso como uma string decimal, conforme o Apple Pay espera.

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

Verifique a disponibilidade e inicie o pagamento

Condicione o botão do Apple Pay a isSupported() (o navegador suporta Apple Pay) e canMakePayments() (o dispositivo tem um cartão utilizável). Quando o cliente toca no botão, chame beginPayment() com uma solicitação de pagamento e um conjunto de callbacks. Em onAuthorized, tokenize o pagamento autorizado e encaminhe a referência de token para o seu 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),
    }
  );
}

O elemento de botão

Você pode renderizar um botão pré-construído e compatível com a Apple em vez de estilizar o seu próprio:

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

No React, use o componente <ApplePayButton>.

Métodos do Apple Pay

Google Pay

O módulo Google Pay carrega a folha de pagamento do Google Pay, captura os dados de pagamento selecionados e os troca por uma referência de token de carteira.

Configurar

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

Verifique a disponibilidade e carregue os dados de pagamento

Condicione o botão do Google Pay a isSupported() (o navegador suporta Google Pay) e isReadyToPay() (o cliente tem um método de pagamento utilizável). Quando o cliente toca no botão, chame loadPaymentData() com uma solicitação de pagamento e, em seguida, tokenize os dados de pagamento retornados.

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 }),
  });
}

O elemento de botão

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

No React, use o componente <GooglePayButton>.

Métodos do Google Pay

Cobre o token a partir do seu servidor

Qualquer que seja o método, o resultado é uma referência tok_…. O seu backend cria a transação com a sua chave secreta, referenciando o token, e envia uma Idempotency-Key para que uma nova tentativa nunca cobre em dobro. Defina payment_method para corresponder ao método que o cliente usou (pix, wallet ou 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"
  }'

A resposta de sucesso é encapsulada no envelope padrão:

{
  "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"
}

O fluxo completo de cobrança — captura, reembolsos e a linha do tempo de tentativas — está em Transações.

Próximos passos

• Visão geral do Bridge SDK — elementos, carteiras, contexto de checkout e o modelo de configuração completo.
• Tokenização — formatos de entrada da tokenização, opções e a resposta de token.
• Elementos — todos os elementos de entrada, incluindo o elemento de CPF usado para o PIX.
• Transações — cobre o token e, em seguida, capture, anule ou reembolse.