> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chargefy.js para browser

> O SDK da Chargefy para tokenizar e salvar cartões no navegador, além de propagar atribuição até o Checkout hospedado.

**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.

<Note>
  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.
</Note>

## 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.

```html theme={"theme":"css-variables"}
<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:

```html theme={"theme":"css-variables"}
<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()`:

```js theme={"theme":"css-variables"}
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.

<Note>
  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.
</Note>

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](/payments/create-payment-link#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.

<Tip>
  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.
</Tip>

## Inicializar

```js theme={"theme":"css-variables"}
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`.       |

<Tip>
  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.
</Tip>

## 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:

```js theme={"theme":"css-variables"}
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

<ParamField body="number" type="string" required>
  Número do cartão. Espaços e traços são ignorados.
</ParamField>

<ParamField body="exp_month" type="number" required>
  Mês de validade (`1`–`12`).
</ParamField>

<ParamField body="exp_year" type="number" required>
  Ano de validade. Aceita 4 dígitos (`2030`) ou 2 dígitos (`30`).
</ParamField>

<ParamField body="cvc" type="string" required>
  Código de segurança (3 ou 4 dígitos).
</ParamField>

<ParamField body="payment_method_data.billing_details.name" type="string" required>
  Nome do titular impresso no cartão.
</ParamField>

## 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.

```js theme={"theme":"css-variables"}
const token = await chargefy.createPaymentToken({
  number: cardNumber,
  exp_month: expMonth,
  exp_year: expYear,
  cvc,
  name: holderName,
});
```

```json theme={"theme":"css-variables"}
{
  "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
}
```

<ResponseField name="id" type="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.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `token`.
</ResponseField>

<ResponseField name="card" type="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.
</ResponseField>

## Consultar o estado no navegador

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

```js theme={"theme":"css-variables"}
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](/api-reference/errors).

```js theme={"theme":"css-variables"}
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.     |

<Warning>
  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](/payments/build-white-label-checkout) no backend — é lá que você trata
  recusa e retry.
</Warning>

### 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](/api-reference/sandbox#falhas-de-cartao).

## 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](mailto:suporte@chargefy.io).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Checkout white-label" icon="bolt" href="/payments/build-white-label-checkout">
    Monte uma tela de pagamento com a sua marca, de ponta a ponta.
  </Card>

  <Card title="Tokenização de cartão" icon="credit-card" href="/payments/save-card-for-later">
    Salve o cartão para cobrar depois (assinaturas, recompra).
  </Card>
</CardGroup>