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 cada chamada feita para https://api.chargefy.io/v1.

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

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.

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.

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 uma Checkout Session ou de um Cadastro de cartão específico quando combinado com a credencial pública esperada. Ele não 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 e token_id 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

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Autenticação e segurança

Autenticar o backend

Escopos da organização

Autenticar o navegador

Chargefy for Platforms: operar organizações filhas

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

​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

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