Skip to main content
Este guia mostra, na prática, como coletar um cartão na sua própria página e transformá-lo em uma credencial reutilizável (pm_*), passo a passo. A regra que mantém o seu PCI baixo: o cartão é tokenizado no navegador do comprador e o seu backend só lida com um token opaco. São três peças, cada uma com um papel:
PeçaPapel
token (tok_*)O cartão recém-digitado, tokenizado no navegador. Uso único.
setup_intent (seti_*)Troca o token por um cartão salvo, sem cobrar.
payment_method (pm_*)O cartão salvo e reutilizável.

​
Passo a passo

1

Carregue o Chargefy.js na sua página

Inclua o script sempre da origem oficial — não faça cópia local, para receber correções de segurança automaticamente.
<script src="https://api.chargefy.io/v1/chargefy.js"></script>
Isso expõe um global Chargefy.
2

Tokenize o cartão no navegador

Inicialize com o ambiente (test ou live) e chame createPaymentToken com os campos do cartão. O resultado é um token de uso único — o número do cartão sai do navegador direto para a Chargefy e nunca toca o seu backend.
const chargefy = Chargefy({ environment: "live" });

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

  // token.id (tok_*) é o que você envia ao backend.
  await fetch("/api/save-card", {
    method: "POST",
    body: JSON.stringify({ token_id: token.id }),
  });
} catch (err) {
  // err.code / err.message — trate na sua UI (ver "Erros").
}
Em environment: "test", o token é sintético e nenhum dado vai para a rede — use os cartões de teste para simular aprovação e recusa.
3

Tenha um customer com documento

O cartão salvo pertence a um cliente. No seu backend, crie (ou reaproveite) o customer com document (CPF/CNPJ) — obrigatório para salvar cartão no Brasil.
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"
  }'
4

Salve o cartão com um setup intent

No backend, confirme um setup intent enviando o token_id. Com confirm: true, você cria e confirma em uma só chamada. A resposta traz o payment_method (pm_*) salvo e já definido como padrão do customer.
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_456",
  "status": "succeeded",
  "usage": "off_session"
}
5

Cobre quando precisar

Com o pm_* salvo, cobre a qualquer momento criando um payment intent que referencia o customer e o payment_method.
curl -X POST "https://api.chargefy.io/v1/payment-intents" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "confirm": true,
    "currency": "brl",
    "customer": "cus_123",
    "payment_method": "pm_456"
  }'

​
Erros

A validação no navegador é a primeira barreira de UX; a aprovação ou recusa definitiva do cartão acontece quando você cobra. O createPaymentToken rejeita a Promise com um erro que carrega type, code, message e, quando aplicável, param.
codeQuando acontece
invalid_numberNúmero do cartão ausente ou com tamanho inválido.
invalid_expiry_month / invalid_expiry_yearValidade inválida.
invalid_cvcCVC com menos de 3 ou mais de 4 dígitos.
invalid_nameNome do titular ausente.
tokenization_failed / invalid_cardO cartão foi recusado na tokenização.
Não reaproveite um token: ele é de uso único. Se a confirmação falhar, gere um novo token e tente de novo.

​
Próximos passos

Tokenização de cartão

O conceito completo: token, setup intent e cartão salvo.

Chargefy.js

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

Objeto token

Contrato do token de uso único.

Checkout white-label

Cobrar cartão na sua própria página, com a sua marca.