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, tokeniza o cartão no próprio navegador e chama POST /v1/setup-intents/{id}/confirm com a credencial de uso único. O número do cartão e o CVC saem do navegador direto para o processador de cartões; nem o seu servidor nem a Chargefy recebem esses dados, e seu código não precisa transportar o token.

Campos do cartão

string

obrigatório

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

number

obrigatório

Mês de validade (1–12).

number

obrigatório

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

string

obrigatório

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

string

obrigatório

Nome do titular impresso no cartão.

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.

Chargefy for Platforms: cadastros das organizações filhas

Esta seção só se aplica ao Chargefy for Platforms, para quem opera pagamentos de suas organizações filhas.

A plataforma recebe automaticamente suas próprias chaves pk_test_* e pk_live_*. Copie a chave do ambiente em Developers → Chaves de API no console da plataforma; não use a chave da organização dona. O backend cria o cadastro na organização filha com a chave secreta da plataforma e o header Organization. No navegador, use a PK da plataforma e o client_secret recebido:

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

A chave e o cadastro precisam ser do mesmo ambiente. A plataforma e o vínculo com a filha devem estar ativos. A chave publicável da organização continua restrita aos cadastros da própria organização, mesmo quando ela possui uma plataforma.

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

confirmSetup rejeita a Promise com um erro que carrega type, code, message e, quando aplicável, param — o mesmo formato dos erros da API. Os campos do cartão são validados no navegador antes de qualquer request:

try {
  await chargefy.confirmSetup({ client_secret: clientSecret, payment_method_data });
} 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.

O número do cartão e o CVC saem do navegador direto para o processador de cartões; eles nunca passam pelo seu servidor nem pela Chargefy, que recebe apenas uma credencial opaca de uso único dentro de confirmSetup().

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; inicie outro cadastro.

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 para o cadastro de cartão e os botões de oferta dos funis; a propagação de atribuição não faz request. Em produção, confirmSetup() também se conecta à origem do processador de cartões para tokenizar no navegador, então uma CSP restritiva precisa liberá-la. Fale com o suporte para obter a origem a liberar. Para que os botões de oferta carreguem a fonte escolhida em Marca, acrescente também estas origens à sua política existente:

style-src https://pay.chargefy.io;
font-src  https://pay.chargefy.io;

O SDK carrega apenas a fonte utilizada pelos botões. A opção Sistema não baixa fontes.

Pagamentos online

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

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

Consultar o estado no navegador

Chargefy for Platforms: cadastros das organizações filhas

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

​Consultar o estado no navegador

​Chargefy for Platforms: cadastros das organizações filhas

​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

Consultar o estado no navegador

Chargefy for Platforms: cadastros das organizações filhas

Como os objetos se encaixam

Erros

Erros ao concluir o cadastro

Cartões de teste

Content Security Policy

Próximos passos