Autenticação e segurança

Na integração server-to-server, a chave secreta identifica a sua própria organização. Ela deve ficar no backend e acompanha as chamadas autenticadas para https://api.chargefy.io/v1. A consulta de saúde dos serviços é pública e dispensa credenciais.

Ter um SaaS, aplicativo ou marketplace próprio não significa que sua conta usa o Chargefy for Platforms. Se você integra os dados e pagamentos da sua própria empresa, siga apenas o fluxo de organização abaixo.

Autenticar o backend

Envie a chave no header Authorization usando Bearer. Não envie o header Organization nesse fluxo.

curl "https://api.chargefy.io/v1/customers?limit=1" \
  -H "Authorization: Bearer {{API_KEY}}"

curl "https://api.chargefy.io/v1/customers?limit=1" \
  -H "X-Chargefy-Api-Key: {{API_KEY}}"

Authorization é o formato recomendado. Use X-Chargefy-Api-Key quando um proxy ou cliente HTTP já reservar o header Authorization. Se ambos forem enviados, X-Chargefy-Api-Key tem prioridade. Uma chave válida retorna a resposta normal do endpoint:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": "/v1/customers"
}

Nunca envie uma chave secreta ch_* para o navegador ou aplicativo mobile. Para os poucos fluxos de browser suportados, use uma chave publicável pk_*.

Escopos da organização

Escopo	Permite
`read`	Consultar e listar recursos com `GET`.
`write`	Tudo de `read`, além de criar, atualizar e executar ações com `POST` ou `DELETE`.
`admin`	Tudo de `write`, além de operações administrativas reservadas.

Os escopos são hierárquicos: write inclui read, e admin inclui os dois. Use o menor acesso necessário para cada integração.

Autenticar o navegador

O Chargefy.js usa uma chave publicável para identificar a organização e o ambiente:

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

A pk_* pode ficar no código do frontend, mas não autoriza nenhum recurso sozinha. No Cadastro de cartão, ela precisa ser combinada com o client_secret exato do setup_intent. Essa dupla permite somente:

consultar GET /v1/setup-intents/{id};
confirmar POST /v1/setup-intents/{id}/confirm com um cartão novo;
tokenizar o cartão internamente para essa confirmação.

Ela não lista recursos, não troca customer, não altera metadata e não substitui uma chave secreta no backend. O ambiente também precisa coincidir: pk_test_* não acessa um cadastro live e pk_live_* não acessa um cadastro de teste.

As chaves publicáveis live e test ficam em Developers → Chaves de API.

Chargefy for Platforms: operar organizações filhas

Este recurso só está disponível para Chargefy for Platforms. Ele se aplica a quem opera pagamentos para suas organizações filhas. Uma chave comum da sua organização não ganha esse comportamento por sua empresa ter um produto chamado de plataforma.

Uma organização filha é uma organização Chargefy independente operada pela sua plataforma. A chave secreta do Chargefy for Platforms usa o escopo exclusivo platform_admin. Nos recursos que pertencem à organização filha, envie o ID dela no header Organization:

curl "https://api.chargefy.io/v1/products?limit=1" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_aVpM5TFjvYnNrJna"

O endpoint determina como a organização filha é escolhida:

Operação	Como o alvo é definido	Header `Organization`
`POST /v1/organizations`	A plataforma autenticada cria uma organização filha.	Não envie.
`GET /v1/organizations`	Lista as organizações filhas acessíveis.	Não envie.
`GET /v1/organizations/{id}`	O `{id}` da URL escolhe a organização filha.	Não envie.
`POST /v1/organizations/{id}`	O `{id}` da URL escolhe a organização filha.	Não envie.
`POST /v1/organizations/{id}/submit`	O `{id}` da URL escolhe a organização filha.	Não envie.
`GET /v1/fee-plans`	Lista os planos de taxas da sua plataforma.	Não envie.
`GET /v1/fee-plans/{id}`	Consulta um plano de taxas da sua plataforma.	Não envie.
Produtos, clientes, checkouts e pagamentos	O recurso pertence à organização filha indicada.	Envie o ID da organização filha.

Não adicione Organization automaticamente a todas as chamadas. Nas rotas de /v1/organizations, a coleção ou o ID da URL já define o contexto. Nas rotas de /v1/fee-plans, o contexto é a própria plataforma da chave.

Guarde o id devolvido ao criar uma organização filha. Ele será usado na URL para gerenciá-la e no header Organization para operar os recursos que pertencem a ela.

Navegador de uma organização filha

Use a chave publicável da plataforma, criada automaticamente nos ambientes teste e produção e disponível no console da plataforma em Developers → Chaves de API. Ela é independente da chave publicável da organização dona.

const chargefy = Chargefy("{{PLATFORM_PUBLISHABLE_KEY}}");
const setupIntent = await chargefy.retrieveSetupIntent(clientSecret);

Nesse fluxo, o cadastro e seu client_secret identificam a organização filha; não é necessário enviar Organization pelo navegador. A plataforma e o vínculo com a filha precisam estar ativos, e o ambiente da chave deve coincidir com o cadastro. A PK da organização dona não acessa cadastros das filhas, e a PK da plataforma não substitui a PK usada na operação própria da organização.

Erros de autenticação

Status e código	Quando acontece	Como corrigir
`401 authentication_failed`	A chave está ausente, inválida, expirada ou revogada.	Confira o header e o ambiente; substitua a credencial quando necessário.
`403 permission_denied`	A chave é válida, mas não tem o escopo exigido.	Use uma chave com o menor escopo que inclua a operação.
`400 invalid_request`	O header `Organization` foi enviado onde não é aceito.	Remova o header e use a URL para definir a organização filha.
`403 permission_denied` no Chargefy for Platforms	A organização filha está ausente, inativa ou fora do alcance da plataforma.	Envie uma organização filha ativa e acessível no contexto exigido.

As mensagens de 401 dizem qual é o problema e, quando existe uma chave na request, qual chave falhou — o prefixo e os quatro últimos caracteres, nunca o segredo inteiro:

Sem credencial

{
  "error": {
    "code": "authentication_failed",
    "message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_API_KEY'). See https://docs.chargefy.io/api-reference/authentication for details.",
    "type": "authentication_error"
  }
}

Chave inválida, revogada ou apagada

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API Key provided: ch_live_***************************************9f2c",
    "type": "authentication_error"
  }
}

Chave expirada

{
  "error": {
    "code": "authentication_failed",
    "message": "Expired API Key provided: ch_live_***************************************9f2c",
    "type": "authentication_error"
  }
}

Chave desconhecida, revogada e apagada devolvem a mesma mensagem de propósito: de fora, nenhuma das três deve ser distinguível. Toda resposta também inclui X-Request-Id. Registre esse header junto do status HTTP e de error.code para facilitar o diagnóstico. Consulte o formato padrão de erros para ver o payload.

Segurança da integração

Uma integração segura separa as responsabilidades do browser, do seu backend e dos webhooks:

Parte	O que recebe	O que faz
Browser	chave `pk_*`, `client_secret` ou URL hospedada	Exibe o checkout e pode consultar ou concluir um cadastro específico.
Seu backend	chave `ch_*`, respostas da API e, opcionalmente, token	Cria recursos, guarda credenciais e toma decisões de negócio.
Chargefy API	Requests autenticadas do seu backend	Processa recursos e devolve URLs ou resultados financeiros.
Seu endpoint de webhook	Eventos assinados	Confirma mudanças financeiras antes do fulfillment.

Proteja as chaves secretas

Nunca coloque uma chave ch_test_ ou ch_live_ em JavaScript público, aplicativo mobile, URL ou repositório.
Armazene chaves em um secret manager ou variável de ambiente protegida.
Use o menor escopo necessário e separe credenciais por ambiente e serviço.
Faça rotação criando uma chave nova, confirmando seu uso e só então revogando a anterior.

Se uma credencial aparecer em commit, log, ticket ou mensagem, trate-a como comprometida e revogue imediatamente. Apagar o valor do local onde ele apareceu não torna a chave segura novamente.

Veja Gerenciar API keys para criação, expiração, rotação e revogação.

Mantenha dados de cartão fora do backend

No checkout hospedado, a Chargefy coleta os dados de pagamento. Em uma experiência customizada, carregue o Chargefy.js diretamente da origem oficial:

<script src="https://api.chargefy.io/v1/chargefy.js"></script>

Inicialize o script com uma chave publicável e use confirmSetup(). O SDK troca PAN e CVC por uma credencial de uso único internamente e confirma o Cadastro de cartão com o client_secret. Não copie o script para sua infraestrutura e não crie um endpoint que receba os dados brutos do cartão. Se sua página usa Content Security Policy, libere https://api.chargefy.io em script-src e connect-src. Mantenha todo o fluxo em HTTPS.

Trate o `client_secret` como credencial limitada

O client_secret permite ao browser consultar ou executar a ação de um recurso específico — um Cadastro de cartão (setup_intent) ou um Payment Intent — quando combinado com a credencial pública esperada. A Checkout Session hospedada não usa secret: a credencial dela é a própria url, endereçada pelo id. Nenhum secret substitui uma chave secreta nem autoriza listas ou ações administrativas.

Entregue-o apenas ao comprador daquela operação.
Não registre o valor em analytics, mensagens de erro ou logs.
Não reutilize um secret entre clientes, pedidos ou ambientes.
Continue fazendo operações privilegiadas no backend com API key.

Verifique todo webhook

Leia o corpo bruto

A assinatura usa exatamente os bytes recebidos. Não faça parse e serialize novamente antes de validar.

Valide assinatura e timestamp

Use webhook-id, webhook-timestamp e webhook-signature com o secret do endpoint. Prefira uma biblioteca compatível com Standard Webhooks.

Deduplique pelo ID

Persista o id (evt_...) com unicidade. Reentregas fazem parte do contrato e não podem repetir a ação de negócio.

Responda rápido

Depois de verificar e persistir ou enfileirar, devolva 2xx. Faça trabalho pesado fora da request de entrega.

Use o procedimento completo em Entrega e assinatura de webhooks.

Reduza dados sensíveis em logs

Não registre:

headers de autenticação, API keys ou secrets de webhook;
PAN, CVC ou payload bruto do formulário de cartão;
client_secret sem necessidade operacional;
documentos pessoais completos quando um identificador interno basta.

Registre IDs públicos, X-Request-Id, status HTTP, error.code e timestamp. O recurso Request oferece um log estruturado da API com credenciais e dados sensíveis mascarados.

Responda a credenciais expostas

Revogue e substitua

Revogue a credencial afetada e crie outra com o menor escopo possível.

Atualize os serviços

Troque o segredo em todos os consumidores e confirme o último uso da chave anterior.

Investigue

Consulte requests e entregas de webhook para identificar atividade fora do padrão.

Remova a origem do vazamento

Limpe logs, histórico e ferramentas de terceiros, registre o incidente e ajuste os controles.

Próximos passos

Gerenciar API keys

Crie, acompanhe, expire, revogue e rotacione credenciais.

Webhooks

Verifique eventos assinados e lide com reentregas.

Erros

Entenda o envelope de erro e as regras de retry.

Checklist de go-live

Revise segurança e operação antes da primeira cobrança real.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Autenticação e segurança

Autenticar o backend

Escopos da organização

Autenticar o navegador

Chargefy for Platforms: operar organizações filhas

Navegador de uma organização filha

Erros de autenticação

Segurança da integração

Proteja as chaves secretas

Mantenha dados de cartão fora do backend

Trate o `client_secret` como credencial limitada

Verifique todo webhook

Reduza dados sensíveis em logs

Responda a credenciais expostas

Próximos passos

Gerenciar API keys

Webhooks

Erros

Checklist de go-live

​Autenticar o backend

​Escopos da organização

​Autenticar o navegador

​Chargefy for Platforms: operar organizações filhas

​Navegador de uma organização filha

​Erros de autenticação

​Segurança da integração

​Proteja as chaves secretas

​Mantenha dados de cartão fora do backend

​Trate o client_secret como credencial limitada

​Verifique todo webhook

​Reduza dados sensíveis em logs

​Responda a credenciais expostas

​Próximos passos

Gerenciar API keys

Webhooks

Erros

Checklist de go-live

Autenticar o backend

Escopos da organização

Autenticar o navegador

Chargefy for Platforms: operar organizações filhas

Navegador de uma organização filha

Erros de autenticação

Segurança da integração

Proteja as chaves secretas

Mantenha dados de cartão fora do backend

Trate o `client_secret` como credencial limitada

Verifique todo webhook

Reduza dados sensíveis em logs

Responda a credenciais expostas

Próximos passos