Checkout white-label

O Checkout white-label é o caminho para cobrar cartão dentro da sua própria experiência: sua URL, sua interface, sua marca e seus estados de pagamento. A Chargefy fica por trás, cuidando da tokenização, do cofre do cartão, da cobrança e dos webhooks. A regra de segurança é simples: o número do cartão e o CVC são tokenizados no navegador do comprador com Chargefy.js. O seu backend nunca recebe dados sensíveis do cartão; ele recebe apenas um token_id de uso único e chama a API da Chargefy com a sua chave secreta.

Use Checkout white-label quando você quer controlar a tela de pagamento inteira. Se preferir uma página pronta da Chargefy, use Checkout Sessions.

Quando usar

Use Checkout white-label quando…	Use checkout hospedado quando…
O pagamento precisa acontecer dentro do seu app, domínio ou fluxo já existente.	Você quer colocar uma página pronta no ar rapidamente.
Sua equipe quer controlar layout, copy, validação visual, loading e retry.	Você não quer construir nem manter os campos de pagamento.
Você quer salvar o cartão e cobrar imediatamente ou depois.	Você quer delegar toda a experiência de checkout para a Chargefy.
Você já tem backend para criar customers, intents e tratar webhooks.	Você prefere criar uma sessão e redirecionar o comprador.

O que fica com quem

Parte	Responsável
Layout, campos, validação visual e mensagens para o comprador	Sua aplicação
Tokenização segura do cartão no navegador	Chargefy.js
Customer, setup intent e payment intent	Seu backend chamando a API Chargefy
Cofre do cartão, cobrança, recusa e webhooks	Chargefy
Confirmação final do pedido, liberação de acesso e conciliação	Seu backend, a partir dos webhooks

Como as peças se encaixam

Objeto	Papel
`token_id` (`tok_*`)	Cartão recém-digitado, tokenizado no browser. É de uso único.
`setup_intent` (`seti_*`)	Troca o `token_id` por um cartão salvo. Não cobra.
`payment_method` (`pm_*`)	Cartão salvo e reutilizável.
`payment_intent` (`pi_*`)	Cobrança. Referencia o customer e o `payment_method`.

Um payment intent é cobrado com um payment_method (pm_*), nunca com um token_id direto. O caminho seguro é sempre token_id → setup_intent → pm_* → payment_intent.

Pagamento imediato

1. Crie ou reutilize um customer

O cartão pertence a um customer. Para cartão no Brasil, crie o customer com document (CPF/CNPJ).

curl -X POST "https://api.chargefy.io/v1/customers" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "11144477735",
    "email": "nome@email.com",
    "name": "Cliente"
  }'

Reutilize o mesmo customer quando o comprador já existir no seu sistema. Assim você mantém cartões salvos, histórico e cobranças futuras no mesmo perfil.

2. Tokenize o cartão no navegador

Na sua tela de pagamento, carregue o Chargefy.js e envie os dados do cartão para tokenização.

<script src="https://api.chargefy.io/v1/chargefy.js"></script>

const chargefy = Chargefy({ environment: "live" });

const token = await chargefy.createPaymentToken({
  cvc: cvc,
  exp_month: expMonth,
  exp_year: expYear,
  name: holderName,
  number: cardNumber,
});

await fetch("/api/pay", {
  body: JSON.stringify({ token_id: token.id }),
  method: "POST",
});

O seu backend recebe token.id (tok_*). Ele não recebe número do cartão, CVC nem dados sensíveis.

3. Salve o cartão

No backend, confirme um setup intent com o token_id. A resposta traz o payment_method (pm_*) que será usado para cobrar.

curl -X POST "https://api.chargefy.io/v1/setup-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true,
    "customer": "cus_123",
    "token_id": "tok_123"
  }'

{
  "id": "seti_123",
  "object": "setup_intent",
  "customer": "cus_123",
  "payment_method": "pm_123",
  "status": "succeeded",
  "usage": "off_session"
}

4. Cobre com o cartão salvo

Crie o payment intent com customer, payment_method e confirm: true.

curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49900,
    "confirm": true,
    "currency": "brl",
    "customer": "cus_123",
    "payment_method": "pm_123"
  }'

Para cartão, a confirmação é síncrona: a resposta já volta com o resultado atual em status.

{
  "id": "pi_123",
  "object": "payment_intent",
  "amount": 49900,
  "currency": "brl",
  "customer": "cus_123",
  "latest_charge": "ch_123",
  "payment_method": "pm_123",
  "status": "succeeded"
}

Mesmo em uma compra avulsa, o cartão salvo fica disponível no customer. Isso permite retry com consentimento, recompra e assinaturas sem pedir os dados de novo.

Parcelamento

Parcelas são definidas em payment_method_options.credit_card.installments no create ou update do payment intent. Não envie parcelamento no confirm.

{
  "amount": 120000,
  "confirm": true,
  "currency": "brl",
  "customer": "cus_123",
  "payment_method": "pm_123",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "count": 3,
        "has_interest": true
      }
    }
  }
}

Campo	Descrição
`count`	Número de parcelas, de `1` a `12`. O limite pode cair conforme o valor da venda.
`has_interest`	`true` = comprador paga os juros do parcelamento. `false` = sua loja absorve os juros.

O objeto retornado detalha o cálculo do parcelamento:

{
  "amount_subtotal": 120000,
  "amount_total": 123600,
  "count": 3,
  "has_interest": true,
  "interest_amount": 3600
}

Enviar installments no corpo do confirm retorna 400. Defina as parcelas no create ou update do payment intent.

UX recomendada

Momento	O que mostrar
Antes de enviar	Valor total, parcelas, bandeira aceita, CPF/CNPJ do customer quando fizer sentido.
Tokenizando	Loading curto no botão. Não envie o formulário duas vezes.
Salvando cartão	Mensagem de processamento discreta. O comprador não precisa ver detalhes de setup intent.
Cobrando	Estado de “processando pagamento” até a resposta do payment intent.
Aprovado	Confirme o pedido visualmente, mas libere acesso/entrega a partir do webhook.
Recusado	Mostre uma mensagem humana e ofereça tentativa com outro cartão.

Recusa e retry

Se o cartão for recusado, o payment intent fica failed e o motivo vem em last_payment_error. Para tentar de novo:

Tokenize um novo cartão no navegador.
Confirme um novo setup intent para gerar outro pm_*.
Crie um novo payment intent com esse pm_*.

Não reutilize um token_id nem reconfirme um payment intent terminado.

{
  "id": "pi_456",
  "object": "payment_intent",
  "amount": 49900,
  "currency": "brl",
  "customer": "cus_123",
  "last_payment_error": {
    "category": "issuer_declined",
    "code": "payment_failed",
    "message": "Payment method was declined"
  },
  "payment_method": "pm_456",
  "status": "failed"
}

3DS e autenticação

Hoje a cobrança de cartão é síncrona: ao confirmar, o status já volta succeeded, requires_capture (quando capture_method: manual) ou failed. Não há etapa de redirecionamento ou desafio 3DS no fluxo de cartão.

next_action existe para métodos assíncronos, como PIX e boleto. Cartão não usa next_action no Checkout white-label.

Webhooks são a fonte da verdade

A resposta síncrona ajuda a atualizar a tela, mas o estado final da sua operação deve vir dos webhooks. Verifique a assinatura antes de processar eventos — veja Entrega de webhooks.

Evento	Quando usar
`payment.intent.succeeded`	Confirmar pagamento aprovado e liberar pedido/acesso.
`payment.intent.failed`	Registrar falha e permitir retry.
`payment.intent.canceled`	Marcar tentativa cancelada.
`setup.intent.succeeded`	Confirmar que o cartão foi salvo no customer.
`payment.method.attached`	Atualizar a lista de cartões salvos do customer.

Uma cobrança de cartão também emite charge.succeeded ou charge.failed. Para o estado do pagamento, escute payment.intent.*; charge.* é o detalhe da tentativa de cobrança.

Erros esperados

Todos seguem o formato de erro { error: { code, message, param, type } }.

Situação	Resposta
Token inválido, expirado ou recusado ao salvar	`402` `card_error` no confirm do setup intent.
Cartão recusado na cobrança	Payment intent `status: failed` com `last_payment_error`.
Parcelas inválidas	`400` em `payment_method_options.credit_card.installments.count`.
`customer` ausente	`400` com `param: customer`.
`payment_method` ausente no confirm de cartão	`400` com `param: payment_method`.
Customer sem documento	`422` — defina `document` (CPF/CNPJ) antes de salvar o cartão.
`payment_method` não pertence ao customer	`400` com `param: payment_method`.

Sandbox

Em test, o número do cartão escolhe o cenário (aprovado, recusado, saldo insuficiente etc.). Use a chave ch_test_ no backend e environment: "test" no Chargefy.js. Veja os cartões de teste em Chargefy.js e os cenários completos em Sandbox.

Próximos passos

Chargefy.js

Referência do script de tokenização no navegador.

Tokenização de cartão

Salve cartão para assinaturas, recompra e cobrança futura.

Payment Intents

Contrato completo de create, confirm, capture e cancel.

Webhooks

Entrega, assinatura e processamento idempotente.

​Quando usar

​O que fica com quem

​Como as peças se encaixam

​Pagamento imediato

​1. Crie ou reutilize um customer

​2. Tokenize o cartão no navegador

​3. Salve o cartão

​4. Cobre com o cartão salvo

​Parcelamento

​UX recomendada

​Recusa e retry

​3DS e autenticação

​Webhooks são a fonte da verdade

​Erros esperados

​Sandbox

​Próximos passos

Chargefy.js

Tokenização de cartão

Payment Intents

Webhooks

Quando usar

O que fica com quem

Como as peças se encaixam

Pagamento imediato

1. Crie ou reutilize um customer

2. Tokenize o cartão no navegador

3. Salve o cartão

4. Cobre com o cartão salvo

Parcelamento

UX recomendada

Recusa e retry

3DS e autenticação

Webhooks são a fonte da verdade

Erros esperados

Sandbox

Próximos passos