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.

Use Checkout white-label quando você quer controlar a tela de pagamento inteira. Se preferir uma página pronta com sua marca e domínio, use Checkout Sessions e configure a apresentação.

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.

Implementar com um assistente MCP

O MCP da Chargefy ajuda o assistente a pesquisar esta documentação, detalhar os contratos disponíveis e consultar o resultado. Criar setup intents e payment intents e confirmar pagamentos são chamadas da API pública no seu backend; coletar o cartão é responsabilidade do Chargefy.js no navegador. Essas ações não são ferramentas de execução do MCP. Um pedido que preserva a escolha de interface própria:

Implemente um checkout próprio com Chargefy.js seguindo este guia. Use o MCP para consultar a documentação e os recursos permitidos. Crie customer e setup intent no backend, colete o cartão com confirmSetup no navegador e cobre com o payment_method salvo. Valide valores e vínculo do comprador no servidor, implemente idempotência e webhooks e teste aprovação, recusa e retry em sandbox.

Para operar pagamentos de organizações filhas, siga também a seção Chargefy for Platforms: o escopo do MCP e as credenciais da API têm papéis diferentes.

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.
`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_*). O número do cartão nunca chega ao seu backend: confirmSetup() tokeniza no navegador e devolve o cartão já salvo.

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": "[email protected]",
    "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": "[email protected]",
  "livemode": false,
  "metadata": {},
  "name": "Cliente",
  "phone": null,
  "trade_name": 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_test_...");

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",
  "...": "campos server-side omitidos no navegador",
  "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"
}

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

Uma aprovação imediata retorna 200 com status: "succeeded", como abaixo. Confira também o status HTTP: em uma recusa, o intent vem dentro de error.payment_intent, conforme a seção Recusa e retry.

{
  "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,
        "installment_interest_amount": 0,
        "interest_payer": "organization",
        "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.

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,
        "interest_payer": "buyer"
      }
    }
  }
}

Campo	Descrição
`count`	Número de parcelas, de `1` a `12`. O limite pode cair conforme o valor da venda.
`interest_payer`	`buyer` = o comprador paga os juros do parcelamento, somados ao total. `organization` = sua loja paga; o comprador parcela o valor à vista e o juro é descontado do seu líquido. Omitido, vale a configuração da organização.

O objeto retornado detalha o cálculo do parcelamento:

{
  "amount": 123600,
  "count": 3,
  "installment_interest_amount": 3600,
  "interest_payer": "buyer",
  "principal_amount": 120000,
  "surcharge_amount": 0
}

Com interest_payer: "organization", o mesmo pedido volta com amount: 120000 e o mesmo installment_interest_amount: 3600: o juro existe, mas é descontado do seu líquido em vez de entrar no total do comprador.

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,
      "eligible": true,
      "minimum_amount": 300,
      "surcharge_amount": 0
    },
    "credit_card": {
      "installments": {
        "max_count": 6,
        "options": [
          {
            "amount": 29900,
            "count": 1,
            "eligible": true,
            "installment_interest_amount": 0,
            "interest_payer": "buyer",
            "minimum_amount": 700,
            "per_installment_amount": 29900,
            "surcharge_amount": 0
          },
          {
            "amount": 30800,
            "count": 2,
            "eligible": true,
            "installment_interest_amount": 900,
            "interest_payer": "buyer",
            "minimum_amount": 2300,
            "per_installment_amount": 15400,
            "surcharge_amount": 0
          },
          {
            "amount": 31105,
            "count": 3,
            "eligible": true,
            "installment_interest_amount": 1205,
            "interest_payer": "buyer",
            "minimum_amount": 3305,
            "per_installment_amount": 10368,
            "surcharge_amount": 0
          },
          {
            "amount": 31410,
            "count": 4,
            "eligible": true,
            "installment_interest_amount": 1510,
            "interest_payer": "buyer",
            "minimum_amount": 4310,
            "per_installment_amount": 7853,
            "surcharge_amount": 0
          },
          {
            "amount": 31718,
            "count": 5,
            "eligible": true,
            "installment_interest_amount": 1818,
            "interest_payer": "buyer",
            "minimum_amount": 5318,
            "per_installment_amount": 6344,
            "surcharge_amount": 0
          },
          {
            "amount": 32030,
            "count": 6,
            "eligible": true,
            "installment_interest_amount": 2130,
            "interest_payer": "buyer",
            "minimum_amount": 6330,
            "per_installment_amount": 5338,
            "surcharge_amount": 0
          }
        ]
      }
    },
    "pix": {
      "amount": 29900,
      "eligible": true,
      "minimum_amount": 101,
      "surcharge_amount": 0
    }
  }
}

A resposta traz payment_methods.credit_card.installments.options[] com count, per_installment_amount, amount e interest_payer 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 — amount = principal_amount + surcharge_amount + installment_interest_amount quando o comprador paga o juro (interest_payer: "buyer"), ou amount = principal_amount + surcharge_amount quando a organização paga (interest_payer: "organization").

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

Uma recusa de cartão retorna HTTP 402, com o motivo em error.code e o Payment Intent completo em error.payment_intent. Esse intent volta para requires_payment_method, com o motivo também em last_payment_error. Guarde o ID mesmo quando a criação com confirm: true responder com erro; assim a próxima tentativa pode usar o mesmo pagamento. Para trocar o cartão:

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. Falhas técnicas podem retornar 502 api_error. Confira error.code, error.advice_code e o estado do intent antes de oferecer outra tentativa. Se o resultado estiver indefinido ou o status for processing, aguarde os webhooks e consulte o mesmo intent. Em timeout, preserve a chave de idempotência da operação; não crie outro pagamento para contornar a falta de resposta. O objeto abaixo é o estado do intent consultado por GET ou obtido em error.payment_intent; não é uma resposta de sucesso da confirmação recusada.

{
  "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,
        "installment_interest_amount": 0,
        "interest_payer": "organization",
        "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

A confirmação pode retornar succeeded, requires_capture (quando capture_method: manual) ou uma resposta de erro com o intent em requires_payment_method. Se o estado for processing, mantenha a tela em processamento e aguarde a confirmação. 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
`confirmSetup()`	Número, CVC ou validade inválidos	Erro de validação no navegador; não envie o formulário ao backend.
Setup intent	Cartão não pôde ser salvo	`402 card_setup_failed`; permita corrigir ou usar outro cartão.
Setup intent	Customer sem documento	`422`; defina `document` (CPF/CNPJ) antes de salvar o cartão.
Payment intent	Cartão recusado	`402 card_error`; `error.payment_intent` contém `status: requires_payment_method` e `last_payment_error`.
Payment intent	Falha técnica na confirmação	Pode retornar `502 api_error`; confira o código e o estado antes de repetir a operação.
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

Esta seção só se aplica a contas com o produto Chargefy for Platforms habilitado, que operam pagamentos para suas organizações filhas.

Se você cobra em nome de organizações filhas, envie o header Organization em todas as chamadas do backend com a chave secreta da plataforma. Customer, setup intent, cartão salvo e payment intent devem pertencer à mesma organização filha e ao mesmo ambiente. No backend, obtenha a organização a partir do vendedor autorizado no seu sistema e confira o vínculo do customer e do payment_method com aquela compra antes de cobrar.

Customer na organização filha

Use a API key da plataforma em {{API_KEY}} nestes exemplos:

curl -X POST "https://api.chargefy.io/v1/customers" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: org_5Nq8rT2wX7mK4pV9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buyer-8f4c2a" \
  -d '{
    "document": "11144477735",
    "email": "[email protected]",
    "name": "Cliente"
  }'

Setup intent e coleta do cartão

Substitua customer pelo ID retornado na etapa anterior:

curl -X POST "https://api.chargefy.io/v1/setup-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: org_5Nq8rT2wX7mK4pV9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: card-registration-8f4c2a" \
  -d '{
    "customer": "cus_6BqaxxG9S6TG8GPU"
  }'

No navegador, use a chave publicável própria da plataforma, emitida no console de Platforms, e o client_secret do setup intent criado na organização filha. Não use a chave publicável da organização dona da plataforma: ela continua restrita aos cadastros daquela organização. A PK e o setup intent devem estar no mesmo ambiente, e a plataforma e o vínculo com a filha devem estar ativos. O navegador não envia o header Organization.

Execute confirmSetup() como no exemplo de navegador acima, com essa chave publicável e esse client_secret, e envie o payment_method retornado ao seu backend.

Cobrança na organização filha

curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Organization: org_5Nq8rT2wX7mK4pV9" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-order-8f4c2a" \
  -d '{
    "amount": 49900,
    "confirm": true,
    "currency": "brl",
    "customer": "cus_6BqaxxG9S6TG8GPU",
    "payment_method": "pm_KBx5LJhsN4L7hnYJ"
  }'

Os IDs são ilustrativos: use os recursos criados para aquela filha. O MCP conectado à organização dona da plataforma pode consultar suas organizações filhas; isso não permite executar cobranças nem criar recursos nelas. A API key de plataforma é usada pelo backend, e não para autenticar o MCP. Veja Autenticação para a matriz de chaves e escopos e Chargefy.js para o exemplo.

Sessões próprias, vários produtos e assinaturas

Quando sua aplicação hospeda a página, ela também pode manter sua própria sessão de compra. Salve uma cópia dos produtos, quantidades, valores e condições antes do pagamento; alterações posteriores na oferta não devem alterar essa sessão. Proteja os dados do comprador com uma credencial de acesso aleatória, e não apenas com o ID público do link. Para uma venda avulsa com vários produtos, some os itens no backend e crie um payment intent para a compra. Consulte as parcelas em Payment previews; envie o número escolhido em payment_method_options.credit_card.installments.count na criação ou atualização do intent, antes de confirmar. Recalcule e confira o total antes de cobrar. O preview segue a configuração de parcelamento da organização, inclusive quem paga o juro (interest_payer). Para uma assinatura, salve o cartão com o mesmo fluxo de setup intent e crie a subscription, com o cartão em default_payment_method, os produtos em items e payment_behavior: "allow_incomplete". A criação já tenta cobrar a primeira invoice. Não crie outro payment intent para essa primeira cobrança. Se a assinatura ficar incompleta, reutilize-a, atualize o cartão padrão e pague sua invoice aberta com o cartão corrigido. Produtos recorrentes da mesma assinatura devem compartilhar moeda e período. Grave a operação antes de enviar a requisição e use Idempotency-Key. Após um timeout, repita a mesma operação com a mesma chave e corpo; não trate a ausência da resposta como uma recusa. O prazo de retenção de idempotência da API não substitui o vínculo durável entre sua sessão e os IDs financeiros já criados. Os webhooks assinados podem chegar repetidos ou fora de ordem. Registre o ID do evento, confira organização e ambiente e releia o recurso para confirmar o estado. Para recorrência, estenda o acesso com o período da invoice paga: leia line_items[].period_start e line_items[].period_end em Obter uma fatura. Não use subscription.current_period_end como prova de uma renovação paga. Mantenha recuperação para eventos perdidos ou falhas temporárias de entrega.

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

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

Criar um checkout white-label

Quando usar

Implementar com um assistente MCP

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

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

Customer na organização filha

Setup intent e coleta do cartão

Cobrança na organização filha

Sessões próprias, vários produtos e assinaturas

Próximos passos

Chargefy.js

Tokenização de cartão

Payment Intents

Webhooks

​Quando usar

​Implementar com um assistente MCP

​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

​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

​Customer na organização filha

​Setup intent e coleta do cartão

​Cobrança na organização filha

​Sessões próprias, vários produtos e assinaturas

​Próximos passos

Chargefy.js

Tokenização de cartão

Payment Intents

Webhooks

Quando usar

Implementar com um assistente MCP

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

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

Customer na organização filha

Setup intent e coleta do cartão

Cobrança na organização filha

Sessões próprias, vários produtos e assinaturas

Próximos passos