Skip to main content
Chargefy.js é o script de browser que transforma os dados de um cartão em um token de uso único (token_id) direto no navegador do comprador. O número do cartão (PAN) e o código de segurança (CVC) nunca passam pelo seu backend — você recebe só um token opaco, que o seu servidor envia para a API com a sua chave secreta. É a peça que falta para montar um Checkout white-label: você controla 100% da UI, e mantém o seu PCI baixo porque os dados sensíveis do cartão saem do navegador direto para a Chargefy.
Chargefy.js só tokeniza. Ele não cobra, não cria customer e não conhece a sua chave secreta. Cobrar e salvar cartão acontecem no seu backend, com o token_id que o script devolve — veja Checkout white-label e Tokenização de cartão.

​
Carregar o script

Inclua o script servido pela Chargefy. Carregue-o 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.

​
Inicializar

const chargefy = Chargefy({ environment: "test" }); // "test" ou "live"
ParâmetroValoresDescrição
environment"test" | "live"Define o ambiente. Em test, o token é sintético e nenhum dado vai para a rede — use os cartões de teste listados abaixo. Em live, o cartão é tokenizado de verdade.
Use test enquanto desenvolve e live em produção, espelhando o ambiente da chave (ch_test_ / ch_live_) que o seu backend usa para confirmar. Misturar ambientes faz a confirmação falhar.

​
Tokenizar um cartão

createPaymentToken recebe os campos do cartão e devolve uma Promise com o token. 
try {
  const token = await chargefy.createPaymentToken({
    number: "4242424242424242",
    exp_month: 12,
    exp_year: 2030,
    cvc: "123",
    name: "MARIA SOUZA",
  });

  // token.id -> envie ao seu backend para confirmar
  console.log(token.id); // "tok_123"
} catch (err) {
  // err.code / err.message — veja "Erros"
}

​
Campos do cartão

​
number
string
required
Número do cartão. Espaços e traços são ignorados.
​
exp_month
number
required
Mês de validade (1–12).
​
exp_year
number
required
Ano de validade. Aceita 4 dígitos (2030) ou 2 dígitos (30).
​
cvc
string
required
Código de segurança (3 ou 4 dígitos).
​
name
string
required
Nome do titular impresso no cartão.

​
O token retornado

{
  "id": "tok_123",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  }
}
​
id
string
O token_id de uso único. Envie ao seu backend e use-o uma vez para confirmar um setup intent ou um payment intent. Depois de consumido, ele morre — para uma nova tentativa, gere outro token.
​
object
string
Sempre token.
​
card
object
Dados não sensíveis para você exibir um resumo do cartão (brand, exp_month, exp_year, last4). O número completo e o CVC nunca são retornados.

​
O que fazer com o token

O token_id é o que liga o browser ao seu backend. O fluxo padrão:
  1. O browser tokeniza e te entrega o token_id.
  2. O seu backend envia o token_id para a Chargefy (com a sua chave secreta) para salvar o cartão (setup intent) e/ou cobrar (payment intent).
  3. O cartão salvo vira um payment_method (pm_*) reutilizável.

​
Erros

createPaymentToken rejeita a Promise com um erro que carrega type, code, message e, quando aplicável, param — o mesmo formato dos erros da API. 
try {
  await chargefy.createPaymentToken(card);
} catch (err) {
  // err.type    -> "card_error" | "invalid_request_error" | "api_error"
  // err.code    -> "invalid_number", "invalid_cvc", "tokenization_failed", ...
  // err.param   -> "number", "cvc", ... (quando o erro é de um campo)
  // err.message -> texto pronto para log (use uma mensagem sua na UI)
}
codeQuando acontece
invalid_numberNúmero do cartão ausente ou com tamanho inválido.
invalid_nameNome do titular ausente.
invalid_expiry_monthMês fora de 1–12.
invalid_expiry_yearAno de validade inválido.
invalid_cvcCVC com menos de 3 ou mais de 4 dígitos.
invalid_environmentChargefy() inicializado sem test/live.
tokenization_failedO cartão foi recusado na tokenização (dados inconsistentes).
invalid_cardO cartão é inválido.
tokenization_unavailableIndisponibilidade temporária — peça para tentar de novo.
A validação no browser é uma primeira barreira de UX, não a decisão final. A aprovação ou recusa do cartão acontece quando você cobra um payment intent no backend — é lá que você trata recusa e retry.

​
Cartões de teste

Em environment: "test", o número do cartão escolhe o cenário. O token é sintético (nenhum dado vai para a rede) e carrega o cenário até a confirmação no backend.
NúmeroResultado na cobrança
4242424242424242Aprovado.
4000000000003220Autorizado para captura posterior.
4000000000000002Recusado com payment_error.code = generic_decline.
4000000000009995Saldo insuficiente.
4000000000000069Cartão expirado.
4000000000000127Código de segurança incorreto.
4000000000000119Erro de processamento.
Use qualquer CVC de 3 dígitos e uma validade futura. A tabela completa de cartões para todos os payment_error.code públicos fica em Sandbox.

​
Content Security Policy

Se a sua página usa CSP, libere a Chargefy para carregar e se comunicar: 
script-src  https://api.chargefy.io;
connect-src https://api.chargefy.io;
O script faz a troca segura do cartão para você. Se a sua CSP for restritiva e a tokenização for bloqueada, fale com o suporte.

​
Próximos passos

Checkout white-label

Monte uma tela de pagamento com a sua marca, de ponta a ponta.

Tokenização de cartão

Salve o cartão para cobrar depois (assinaturas, recompra).