Payment methods (PIX, boleto, Apple Pay, Google Pay)

A single Bridge SDK instance covers every payment method your merchant has enabled. Cards, PIX, boleto, Apple Pay, and Google Pay all share the same flow: the customer pays in the browser, the SDK returns a short-lived token reference, and you forward only that reference to your backend to charge. Cards and wallets return a tok_…; PIX and boleto return a payer token (ptk_…) that holds the payer's details.

This page documents the PIX, boleto, Apple Pay, and Google Pay modules. For card collection, see Tokenization and the SDK quickstart.

How it fits together

Every method produces the same kind of token reference. The browser never holds raw payment credentials, and the actual charge happens server-side with your secret key.

Discover enabled methods

Which methods are available depends on what the merchant has enabled in the Tokeflow Dashboard during onboarding. Read them at runtime instead of hardcoding a payment UI.

Call tokeflow.getAvailablePaymentMethods() (valid after init()), or use the useAvailablePaymentMethods() React hook. It returns a subset of 'cards', 'pix', 'boleto', 'applePay', and '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 (Brazil)

PIX is Brazil's instant payment method. The Bridge SDK registers the payer — name, email and CPF or CNPJ — and returns a payer token (ptk_…). Your server charges it with payer_token_id, so it never handles the payer's document.

Create a CPF element, then call tokeflow.pix.tokenize(). name, email and phone can be secure text elements or plain strings.

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

The SDK checks the CPF/CNPJ check digits before the request (alphanumeric CNPJs included); Tokeflow checks every field again.

The PixToken response

tokeflow.pix.tokenize() resolves to a PixToken. The only field you send onward is tokenId; the rest is non-sensitive display metadata.

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

Boleto (Brazil)

A boleto is a bank slip the customer pays by its digitable line or barcode, usually within a few days. boleto is listed by getAvailablePaymentMethods() only when a connector the merchant routes boleto to can charge one; otherwise boleto.tokenize() throws PAYMENT_METHOD_DISABLED.

tokeflow.boleto.tokenize() registers the payer and returns a payer token. A boleto also needs the billing address. Each field can be a secure element or a plain string.

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

The SDK checks the CPF/CNPJ, the CEP and the UF before the request. A field error throws VALIDATION_ERROR — or INVALID_DOCUMENT for the CPF/CNPJ — and error.details.fields maps each failing field (for example address.postalCode) to its messages.

Charging a PIX or boleto token

Your server creates the transaction with the token as payer_token_id and returns payment_instructions to the browser:

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

A payer token is single use — a failed charge spends it too — and, when collected inside a checkout session, can only be charged with that checkout_session_id. An unusable token is refused with 400 INVALID_PAYER_TOKEN and nothing is charged. The token's email does not link the charge to an existing customer by itself: send customer_id, or the same email from your server. Full rules: PIX and boleto payers.

To show the result, render qr_code_text (copia e cola) and qr_code_url for PIX. For a boleto, the React <BoletoInstructions> component renders the digitable line, a copy button, the due date and a link to the slip.

Apple Pay

The Apple Pay module presents the native Apple Pay sheet, captures the authorized payment in the browser, and exchanges it for a wallet token reference. Apple Pay is available only on supported Apple devices and browsers.

Configure

Configure the module once after init(). Money in the payment request is expressed as a decimal string, as Apple Pay expects.

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

Check availability and begin payment

Gate the Apple Pay button behind isSupported() (the browser supports Apple Pay) and canMakePayments() (the device has a usable card). When the customer taps the button, call beginPayment() with a payment request and a set of callbacks. In onAuthorized, tokenize the authorized payment and forward the token reference to your server.

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

The button element

You can render a prebuilt, Apple-compliant button instead of styling your own:

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

In React, use the <ApplePayButton> component.

Apple Pay methods

Google Pay

The Google Pay module loads the Google Pay payment sheet, captures the selected payment data, and exchanges it for a wallet token reference.

Configure

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

Check availability and load payment data

Gate the Google Pay button behind isSupported() (the browser supports Google Pay) and isReadyToPay() (the customer has a usable payment method). When the customer taps the button, call loadPaymentData() with a payment request, then tokenize the returned payment data.

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

The button element

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

In React, use the <GooglePayButton> component.

Google Pay methods

Charge the token from your server

Whatever the method, the result is a tok_… reference. Your backend creates the transaction with your secret key, referencing the token, and sends an Idempotency-Key so a retry never double-charges. Set payment_method to match the method the customer used (pix, wallet, or 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"
  }'

The success response is wrapped in the standard envelope:

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

The full charge flow — capture, refunds, and the attempt timeline — lives in Transactions.

Next steps

• Bridge SDK overview — elements, wallets, checkout context, and the full configuration model.
• Tokenization — tokenize input shapes, options, and the token response.
• Elements — every input element, including the CPF element used for PIX.
• Transactions — charge the token, then capture, void, or refund.