Criar um checkout white-label

Um checkout white-label permite cobrar cartão dentro da sua própria experiência: sua URL, sua interface, sua marca e seus estados de pagamento. A Chargefy cuida da tokenização, do cartão salvo, da cobrança e dos webhooks. A regra de segurança é simples: o número do cartão e o CVC são tratados no navegador do comprador com Chargefy.js. O seu backend cria o cadastro e entrega o client_secret; o SDK conclui a coleta e devolve somente um payment_method reutilizável. O token de uso único fica interno.

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

Necessidade	Checkout white-label	Checkout hospedado
Interface	Sua equipe cria e mantém toda a tela.	A Chargefy entrega uma página pronta.
Integração	Seu backend cria customers e intents; seu frontend usa Chargefy.js.	Seu backend cria uma Checkout Session e redireciona o comprador.
Melhor escolha	O pagamento precisa fazer parte do seu produto ou fluxo atual.	Você quer começar mais rápido e manter menos código de checkout.

O que fica com quem

Responsabilidade	Quem cuida	Resultado
Layout, campos, validação e mensagens	Sua aplicação	A experiência segue o design do seu produto.
Customer, setup intent e payment intent	Seu backend	A operação fica ligada aos seus pedidos e clientes.
Tokenização, cartão salvo, cobrança e webhooks	Chargefy	Dados sensíveis não passam pelo seu servidor.
Liberação do pedido e conciliação	Seu backend	O produto reage ao estado financeiro confirmado.

Como as peças se encaixam

Recurso	Nasce onde	Papel
`customer` (`cus_*`)	Seu backend	Representa o comprador e reúne seus métodos de pagamento.
`setup_intent` (`seti_*`)	Seu backend	Coordena o cadastro do cartão sem fazer uma cobrança.
`token` (`tok_*`)	Navegador	Credencial de uso único; fica interna no fluxo recomendado.
`payment_method` (`pm_*`)	Resultado do setup intent	Cartão salvo e reutilizável.
`payment_preview`	Seu backend, sob demanda	Calcula as opções de parcelamento para exibição.
`payment_intent` (`pi_*`)	Seu backend	Representa e processa a cobrança.

Um payment intent é cobrado com um payment_method (pm_*). No fluxo recomendado, seu código não transporta token_id: Chargefy.js cuida da credencial intermediária dentro de confirmSetup().

Etapa	Quem faz	Resultado
Criar customer e setup intent	Seu backend	A página recebe o `client_secret`.
Chamar `confirmSetup()` com a chave `pk_*`	Sua página	O backend recebe o `payment_method` (`pm_*`).
Criar e confirmar o payment intent	Seu backend	A cobrança é processada.
Confirmar o resultado	Chargefy e seu webhook	Seu sistema libera o pedido a partir do evento assinado.

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

{
  "id": "cus_6BqaxxG9S6TG8GPU",
  "object": "customer",
  "billing_address": null,
  "billing_name": null,
  "created_at": "2026-05-16T14:09:27Z",
  "document": "11144477735",
  "document_type": "cpf",
  "email": "nome@email.com",
  "livemode": false,
  "metadata": {},
  "name": "Cliente",
  "phone": null,
  "updated_at": "2026-05-16T14:09:27Z"
}

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. Inicie o cadastro no backend

Crie um setup intent para o customer. Envie o client_secret retornado somente à página que vai coletar o cartão.

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

{
  "id": "seti_hiQ7BG6sAs1MUUqD",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_hiQ7BG6sAs1MUUqD_secret_50c02fdda1045cd2b8410bdf0dfabbf3ced11e538205a35b",
  "created_at": "2026-05-16T14:09:27Z",
  "customer": "cus_6BqaxxG9S6TG8GPU",
  "last_setup_error": null,
  "latest_attempt": null,
  "livemode": false,
  "metadata": {},
  "next_action": null,
  "payment_method": null,
  "payment_method_types": [
    "credit_card"
  ],
  "status": "requires_payment_method",
  "updated_at": "2026-05-16T14:09:27Z",
  "usage": "off_session"
}

O client_secret, combinado com a chave publicável, autoriza consultar e concluir somente esse cadastro. Envie-o à página do comprador, mas não o coloque em analytics, logs ou mensagens.

3. Salve o cartão no navegador

Na sua tela de pagamento, carregue o Chargefy.js, use a chave publicável do mesmo ambiente e conclua o cadastro.

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

const chargefy = Chargefy("pk_live_...");

const setupIntent = await chargefy.confirmSetup({
  client_secret: clientSecret,
  payment_method_data: {
    type: "credit_card",
    card: {
      cvc,
      exp_month: expMonth,
      exp_year: expYear,
      number: cardNumber,
    },
    billing_details: { name: holderName },
  },
});

await fetch("/api/pay", {
  body: JSON.stringify({ payment_method: setupIntent.payment_method }),
  headers: { "Content-Type": "application/json" },
  method: "POST",
});

{
  "id": "seti_hiQ7BG6sAs1MUUqD",
  "object": "setup_intent",
  "client_secret": "seti_hiQ7BG6sAs1MUUqD_secret_50c02fdda1045cd2b8410bdf0dfabbf3ced11e538205a35b",
  "created_at": "2026-05-16T14:09:27Z",
  "last_setup_error": null,
  "livemode": false,
  "next_action": null,
  "payment_method": "pm_KBx5LJhsN4L7hnYJ",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "usage": "off_session",
  "...": "campos server-side omitidos no navegador"
}

Seu backend recebe apenas o pm_*; número e CVC não chegam à sua aplicação.

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_6BqaxxG9S6TG8GPU",
    "payment_method": "pm_KBx5LJhsN4L7hnYJ"
  }'

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

{
  "id": "pi_gJqVoyMfiUojAqjh",
  "object": "payment_intent",
  "amount": 49900,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 49900,
    "installment_interest_amount": 0,
    "principal_amount": 49900,
    "surcharge_amount": 0
  },
  "amount_received": 49900,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_gJqVoyMfiUojAqjh_secret_50c02fdda1045cd2b8410bdf0dfabbf3ced11e538205a35b",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "customer": "cus_6BqaxxG9S6TG8GPU",
  "installment_interest_amount": 0,
  "installments": 1,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": "ch_QeVsTnP4qUoNUEJ4",
  "livemode": false,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_KBx5LJhsN4L7hnYJ",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 49900,
        "count": 1,
        "has_interest": false,
        "installment_interest_amount": 0,
        "principal_amount": 49900,
        "surcharge_amount": 0
      }
    }
  },
  "payment_method_types": [
    "credit_card"
  ],
  "principal_amount": 49900,
  "status": "succeeded",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T14:09:27Z"
}

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.

Controle explícito do token

Na maioria das integrações, confirmSetup() é o caminho mais simples: o SDK mantém o token de uso único no navegador e devolve diretamente o payment_method. Algumas integrações, porém, precisam transportar o token_id no próprio backend antes de salvar o cartão.

Fluxo	O que seu backend recebe	Quando usar
`confirmSetup()`	Apenas o `payment_method` (`pm_*`)	Recomendado para integrações novas.
`createPaymentToken()` + API	Primeiro `token_id` (`tok_*`), depois `payment_method`	Quando seu backend precisa controlar explicitamente a confirmação do setup intent.

Os dois caminhos produzem o mesmo cartão salvo. A diferença está apenas em quem transporta a credencial intermediária.

1. Tokenize o cartão no navegador

O número do cartão continua indo diretamente do navegador para a Chargefy. Sua página envia somente token.id ao backend.

const chargefy = Chargefy("pk_live_...");

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

await fetch("/api/card-setup", {
  body: JSON.stringify({ token_id: token.id }),
  headers: { "Content-Type": "application/json" },
  method: "POST",
});

{
  "id": "tok_LVQ6vLBbNwRiXZNx",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  },
  "created_at": "2026-05-16T18:34:58Z",
  "livemode": false
}

2. Troque o token por um cartão salvo

No backend, crie e confirme o setup intent em uma única chamada. O token é de uso único; se a operação falhar antes de salvar o cartão, gere outro.

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_6BqaxxG9S6TG8GPU",
    "token_id": "tok_LVQ6vLBbNwRiXZNx"
  }'

{
  "id": "seti_bsqCqbDRTVRWZh2y",
  "object": "setup_intent",
  "canceled_at": null,
  "cancellation_reason": null,
  "client_secret": "seti_bsqCqbDRTVRWZh2y_secret_50c02fdda1045cd2b8410bdf0dfabbf3ced11e538205a35b",
  "created_at": "2026-05-16T14:09:27Z",
  "customer": "cus_6BqaxxG9S6TG8GPU",
  "last_setup_error": null,
  "latest_attempt": "setatt_T9wQa3mKp6XsR2vN",
  "livemode": false,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_KBx5LJhsN4L7hnYJ",
  "payment_method_types": [
    "credit_card"
  ],
  "status": "succeeded",
  "updated_at": "2026-05-16T14:09:27Z",
  "usage": "off_session"
}

A partir daqui, use o mesmo fluxo desta página: consulte a payment preview quando houver parcelas e crie o payment intent com o pm_* retornado.

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_6BqaxxG9S6TG8GPU",
  "payment_method": "pm_KBx5LJhsN4L7hnYJ",
  "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": 123600,
  "count": 3,
  "has_interest": true,
  "installment_interest_amount": 3600,
  "principal_amount": 120000,
  "surcharge_amount": 0
}

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

Exiba o valor exato das parcelas

No Brasil, Payment Previews serve basicamente para uma coisa: exibir no seu checkout a quantidade de parcelas e o valor exato de cada uma, já com o acréscimo calculado — antes de criar o payment intent, sem você calcular juro na mão.

curl -X POST "https://api.chargefy.io/v1/payment-previews" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29900
  }'

{
  "object": "payment_preview",
  "amount": 29900,
  "currency": "brl",
  "has_surcharge": false,
  "livemode": false,
  "payment_methods": {
    "boleto": {
      "amount": 29900,
      "surcharge_amount": 0
    },
    "credit_card": {
      "installments": {
        "max_count": 6,
        "options": [
          {
            "amount": 29900,
            "count": 1,
            "installment_interest_amount": 0,
            "per_installment_amount": 29900,
            "surcharge_amount": 0
          },
          {
            "amount": 30800,
            "count": 2,
            "installment_interest_amount": 900,
            "per_installment_amount": 15400,
            "surcharge_amount": 0
          },
          {
            "amount": 31105,
            "count": 3,
            "installment_interest_amount": 1205,
            "per_installment_amount": 10368,
            "surcharge_amount": 0
          },
          {
            "amount": 31410,
            "count": 4,
            "installment_interest_amount": 1510,
            "per_installment_amount": 7853,
            "surcharge_amount": 0
          },
          {
            "amount": 31718,
            "count": 5,
            "installment_interest_amount": 1818,
            "per_installment_amount": 6344,
            "surcharge_amount": 0
          },
          {
            "amount": 32030,
            "count": 6,
            "installment_interest_amount": 2130,
            "per_installment_amount": 5338,
            "surcharge_amount": 0
          }
        ]
      }
    },
    "pix": {
      "amount": 29900,
      "surcharge_amount": 0
    }
  }
}

A resposta traz payment_methods.credit_card.installments.options[] com count, per_installment_amount e amount de cada opção — a tabela pronta para o seu seletor de parcelas — além dos totais de pix e boleto no mesmo payload. Quando o comprador escolher, envie o count no create ou update do payment intent. A Chargefy recalcula tudo no servidor; a preview serve apenas para exibição.

Repasse de taxa (surcharge)

Se você quer que o comprador cubra a taxa da organização — a organização recebe líquido exatamente o amount —, envie has_surcharge: true na preview e no payment intent. Os totais passam a incluir surcharge_amount, e no intent a decomposição fica em amount_details (principal_amount + surcharge_amount + installment_interest_amount = amount).

{
  "amount": 49900,
  "confirm": true,
  "currency": "brl",
  "customer": "cus_6BqaxxG9S6TG8GPU",
  "has_surcharge": true,
  "payment_method": "pm_KBx5LJhsN4L7hnYJ"
}

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, a tentativa termina, mas o Payment Intent volta para requires_payment_method com o motivo em last_payment_error. Para tentar de novo:

Crie um novo setup intent no backend.
Chame confirmSetup() com o novo client_secret e os dados corrigidos.
Atualize o mesmo Payment Intent com esse pm_*.
Confirme novamente o mesmo Payment Intent.

O SDK cria uma nova credencial intermediária a cada confirmação. Uma charge recusada é terminal; o Payment Intent em requires_payment_method continua sendo o mesmo pagamento e aceita uma nova tentativa com dados corrigidos ou outro método.

{
  "id": "pi_W7oFRyMy4kL2izn4",
  "object": "payment_intent",
  "amount": 49900,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 49900,
    "installment_interest_amount": 0,
    "principal_amount": 49900,
    "surcharge_amount": 0
  },
  "amount_received": 0,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_W7oFRyMy4kL2izn4_secret_50c02fdda1045cd2b8410bdf0dfabbf3ced11e538205a35b",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T14:09:27Z",
  "currency": "brl",
  "customer": "cus_6BqaxxG9S6TG8GPU",
  "installment_interest_amount": 0,
  "installments": 1,
  "invoice": null,
  "last_payment_error": {
    "advice_code": "do_not_try_again",
    "category": "issuer_declined",
    "code": "transaction_not_permitted",
    "message": "This type of transaction is not permitted for the cardholder.",
    "network_advice_code": null,
    "network_decline_code": "57"
  },
  "latest_charge": "ch_7VgNwPqR2sKdYuMa",
  "livemode": false,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_Bmt4b1FYQDnGVYzt",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 49900,
        "count": 1,
        "has_interest": false,
        "installment_interest_amount": 0,
        "principal_amount": 49900,
        "surcharge_amount": 0
      }
    }
  },
  "payment_method_types": [
    "credit_card"
  ],
  "principal_amount": 49900,
  "status": "requires_payment_method",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T14:09:27Z"
}

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 requires_payment_method na recusa. Não há etapa de redirecionamento ou desafio 3DS no fluxo de cartão.

Cartão não usa next_action neste checkout white-label. O campo aparece em métodos assíncronos: Pix no fluxo direto e boleto quando o intent nasce de checkout hospedado ou invoice.

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.
`charge.failed`	Registrar a tentativa recusada; o intent volta a `requires_payment_method` e aceita 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 } }.

Onde	Situação	Resultado
`createPaymentToken()`	Número, CVC ou validade inválidos	Erro de validação no navegador; não envie o formulário ao backend.
Setup intent	Token inválido, expirado ou recusado	`402 card_error`; gere outro token antes de repetir o fluxo explícito.
Setup intent	Customer sem documento	`422`; defina `document` (CPF/CNPJ) antes de salvar o cartão.
Payment intent	Cartão recusado	`status: requires_payment_method` com `last_payment_error`.
Payment intent	Parcelas inválidas	`400` em `payment_method_options.credit_card.installments.count`.
Payment intent	`customer` ou `payment_method` ausente	`400` com o campo correspondente em `param`.
Payment intent	O método 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 ch_test_* no backend e pk_test_* no Chargefy.js. Veja os cartões de teste em Chargefy.js e os cenários completos em Sandbox.

Chargefy for Platforms

Se você cobra em nome de organizações filhas, envie o header Organization em todas as chamadas do backend. No navegador, a chave publicável e o client_secret precisam pertencer à mesma organização e ao mesmo ambiente. Veja Autenticação para a matriz de chaves e escopos.

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.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Criar um checkout white-label

Quando usar

O que fica com quem

Como as peças se encaixam

Pagamento imediato

1. Crie ou reutilize um customer

2. Inicie o cadastro no backend

3. Salve o cartão no navegador

4. Cobre com o cartão salvo

Controle explícito do token

1. Tokenize o cartão no navegador

2. Troque o token por um cartão salvo

Parcelamento

Exiba o valor exato das parcelas

Repasse de taxa (surcharge)

UX recomendada

Recusa e retry

3DS e autenticação

Webhooks são a fonte da verdade

Erros esperados

Sandbox

Chargefy for Platforms

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. Inicie o cadastro no backend

​3. Salve o cartão no navegador

​4. Cobre com o cartão salvo

​Controle explícito do token

​1. Tokenize o cartão no navegador

​2. Troque o token por um cartão salvo

​Parcelamento

​Exiba o valor exato das parcelas

​Repasse de taxa (surcharge)

​UX recomendada

​Recusa e retry

​3DS e autenticação

​Webhooks são a fonte da verdade

​Erros esperados

​Sandbox

​Chargefy for Platforms

​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. Inicie o cadastro no backend

3. Salve o cartão no navegador

4. Cobre com o cartão salvo

Controle explícito do token

1. Tokenize o cartão no navegador

2. Troque o token por um cartão salvo

Parcelamento

Exiba o valor exato das parcelas

Repasse de taxa (surcharge)

UX recomendada

Recusa e retry

3DS e autenticação

Webhooks são a fonte da verdade

Erros esperados

Sandbox

Chargefy for Platforms

Próximos passos