Chargefy.js para browser

Chargefy.js é o SDK de browser da Chargefy. Ele oferece dois módulos independentes:

Chargefy.Checkout, para preservar a atribuição de campanha ao enviar o comprador para uma página hospedada;
Chargefy(), para salvar um cartão no seu checkout white-label e devolver um payment_method reutilizável.

Chargefy.js não cobra nem cria customer. O backend cria o cadastro com uma chave secreta; o navegador usa uma chave publicável e o client_secret daquele cadastro.

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.

Propagar atribuição para o Checkout hospedado

Use Chargefy.Checkout.trackLinks() na página que recebe o tráfego da campanha:

<script src="https://api.chargefy.io/v1/chargefy.js"></script>
<script>
  Chargefy.Checkout.trackLinks();
</script>

O SDK guarda o primeiro conjunto válido de parâmetros de campanha no localStorage da origem atual e os adiciona aos links de Checkout Session e Payment Link encontrados na página. Ele observa também:

links inseridos depois do carregamento;
mudanças de href;
navegação por pushState, replaceState e popstate em aplicações SPA.

URLs criadas por JavaScript

Quando o redirect não parte de uma tag <a>, use Chargefy.Checkout.createTrackedUrl():

const checkoutUrl = Chargefy.Checkout.createTrackedUrl(originalCheckoutUrl);

window.location.assign(checkoutUrl);

O método recebe uma URL e devolve uma string. URLs que não são reconhecidas como https://pay.chargefy.io/session/... ou https://pay.chargefy.io/link/... voltam sem alteração.

Dados propagados

Grupo	Parâmetros
UTM	`utm_id`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_source_platform`, `utm_creative_format`, `utm_marketing_tactic`
Click IDs	`fbclid`, `gclid`, `gbraid`, `wbraid`, `ttclid`, `msclkid`
Contexto gerado pelo SDK	identificador do first-touch, landing page e referrer

A landing page e o referrer são reduzidos a origem + path. Query string e fragmento não são armazenados nem propagados.

O SDK não copia a query string inteira, não lê cookies de mídia e não captura e-mail, telefone, client_secret ou parâmetros desconhecidos. Ele também não faz request de rede para atribuição: apenas grava o snapshot local e atualiza os links reconhecidos.

Parâmetros que já estiverem na URL do link são preservados: o SDK apenas acrescenta a atribuição. Isso inclui os parâmetros de URL de pré-preenchimento (prefilled_email, locked_prefilled_email, prefilled_promo_code, locale e client_reference_id).

Regras de precedência

O primeiro conjunto de campanha salvo na origem é preservado enquanto aquele armazenamento existir.
Um parâmetro já escrito explicitamente na URL de destino vence o valor salvo.
Chamadas repetidas de trackLinks() são idempotentes e não duplicam parâmetros ou observadores.

O localStorage é isolado por origem. Se a campanha entrar em mais de um domínio seu, carregue o SDK e chame trackLinks() em cada domínio que contém links para o Checkout hospedado.

Inicializar

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

Prefixo	Ambiente	Uso
`pk_test_*`	Teste	Dados e cartões de sandbox, com `livemode: false`.
`pk_live_*`	Produção	Cartões e dados reais, com `livemode: true`.

Copie as duas chaves publicáveis em Developers → Chaves de API. O ambiente vem da própria chave e precisa coincidir com o cadastro criado pelo backend.

Salvar o cartão

O backend cria um setup_intent com customer e entrega o client_secret à página. O navegador chama confirmSetup() e recebe diretamente o cartão salvo:

try {
  const setupIntent = await chargefy.confirmSetup({
    client_secret: clientSecret,
    payment_method_data: {
      type: "credit_card",
      card: {
        number: "4242424242424242",
        exp_month: 12,
        exp_year: 2030,
        cvc: "123",
      },
      billing_details: {
        name: "MARIA SOUZA",
      },
    },
  });

  console.log(setupIntent.status); // "succeeded"
  console.log(setupIntent.payment_method); // "pm_*"
} catch (err) {
  // err.type, err.code, err.param e err.message
}

O SDK valida os campos, cria uma credencial de uso único internamente e chama POST /v1/setup-intents/{id}/confirm. Seu código não precisa transportar o token.

Campos do cartão

string

required

Número do cartão. Espaços e traços são ignorados.

number

required

Mês de validade (1–12).

number

required

Ano de validade. Aceita 4 dígitos (2030) ou 2 dígitos (30).

string

required

Código de segurança (3 ou 4 dígitos).

string

required

Nome do titular impresso no cartão.

API de baixo nível: token

createPaymentToken() continua disponível para integrações que realmente precisam controlar a credencial intermediária. Ele não é necessário no fluxo recomendado de Cadastro de cartão.

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

{
  "id": "tok_rhrbcLJzQRMHmQWN",
  "object": "token",
  "card": {
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2030,
    "last4": "4242"
  },
  "created_at": "2026-05-16T14:09:27Z",
  "livemode": false
}

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.

string

Sempre token.

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.

Consultar o estado no navegador

Use o mesmo client_secret para recuperar o cadastro sem expor a chave secreta do backend:

const setupIntent = await chargefy.retrieveSetupIntent(clientSecret);

if (setupIntent.status === "requires_payment_method") {
  // mostre o formulário para outro cartão
}

A resposta de browser é limitada aos campos que a tela precisa. Ela não traz customer, metadata, histórico de tentativas ou outros dados da conta.

Como os objetos se encaixam

Etapa	Responsável	Resultado
1	Backend com `ch_*`	Cria o `setup_intent` para um customer.
2	Browser com `pk_*` + `client_secret`	`confirmSetup()` coleta e confirma o cartão.
3	Chargefy	Vincula o `payment_method` ao customer e registra um `setup_attempt`.
4	Backend	Usa o `pm_*` numa cobrança futura.

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)
}

`code`	Quando acontece
`invalid_number`	Número do cartão ausente ou com tamanho inválido.
`invalid_name`	Nome do titular ausente.
`invalid_expiry_month`	Mês fora de `1`–`12`.
`invalid_expiry_year`	Ano de validade inválido.
`invalid_cvc`	CVC com menos de 3 ou mais de 4 dígitos.
`invalid_publishable_key`	`Chargefy()` inicializado sem uma chave `pk_*` válida.
`tokenization_failed`	O cartão foi recusado na tokenização (dados inconsistentes).
`invalid_card`	O cartão é inválido.
`tokenization_unavailable`	Indisponibilidade 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.

Erros ao concluir o cadastro

confirmSetup rejeita a Promise no mesmo formato. Os códigos que a tela precisa tratar são:

`code`	Quando acontece	O que fazer
`parameter_missing`	Faltou `client_secret` ou `payment_method_data`.	Corrija a integração.
`resource_missing`	O segredo não identifica um cadastro válido.	Busque outro cadastro pelo backend.
`setup_intent_customer_required`	O cadastro foi criado sem customer.	Vincule o customer pelo backend.
`card_setup_failed`	O cartão não pôde ser salvo.	Permita corrigir ou usar outro cartão.
`resource_state_conflict`	O cadastro já terminou.	Consulte o estado no backend; não reutilize o token.

Cartões de teste

Com pk_test_*, o número do cartão escolhe o cenário. A credencial interna é sintética e carrega o cenário até a confirmação.

Número	Resultado na cobrança
`4242424242424242`	Aprovado.
`4000000000003220`	Autorizado para captura posterior.
`4000000000000002`	Recusado com `payment_error.code = generic_decline`.
`4000000000009995`	Saldo insuficiente.
`4000000000000069`	Cartão expirado.
`4000000000000127`	Código de segurança incorreto.
`4000000000000119`	Erro 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;

script-src permite carregar o SDK. connect-src é necessário apenas para tokenização live; a propagação de atribuição não faz request. Se a sua CSP for restritiva e a tokenização for bloqueada, fale com o suporte.

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Chargefy.js para browser

Carregar o script

Propagar atribuição para o Checkout hospedado

URLs criadas por JavaScript

Dados propagados

Regras de precedência

Inicializar

Salvar o cartão

Campos do cartão

API de baixo nível: token

Consultar o estado no navegador

Como os objetos se encaixam

Erros

Erros ao concluir o cadastro

Cartões de teste

Content Security Policy

Próximos passos

Checkout white-label

Tokenização de cartão

​Carregar o script

​Propagar atribuição para o Checkout hospedado

​URLs criadas por JavaScript

​Dados propagados

​Regras de precedência

​Inicializar

​Salvar o cartão

​Campos do cartão

​API de baixo nível: token

​Consultar o estado no navegador

​Como os objetos se encaixam

​Erros

​Erros ao concluir o cadastro

​Cartões de teste

​Content Security Policy

​Próximos passos

Checkout white-label

Tokenização de cartão

Carregar o script

Propagar atribuição para o Checkout hospedado

URLs criadas por JavaScript

Dados propagados

Regras de precedência

Inicializar

Salvar o cartão

Campos do cartão

API de baixo nível: token

Consultar o estado no navegador

Como os objetos se encaixam

Erros

Erros ao concluir o cadastro

Cartões de teste

Content Security Policy

Próximos passos