Conceitos
Autenticação e chaves
A API pública usa chaves de servidor. Cada chave pertence a uma organização e a um ambiente, tem escopos e uma lista de contas que pode operar.
Como autenticar
Envie a chave no header Authorization e a conta em X-Account-Id. O header de conta escolhe uma das contas permitidas pela chave; ele nunca concede acesso a outra conta.
GET /v1/account HTTP/1.1
Authorization: Bearer ep_test_Ab12Cd34_<segredo>
X-Account-Id: acc_01JDY7Q2M3N4P5R6S7T8V9W0XB| Prefixo | Ambiente | Uso |
|---|---|---|
ep_test_ | Sandbox | Integração e testes; nenhum valor real é cobrado. |
ep_live_ | Produção | Dinheiro real; disponível só para contas aprovadas. |
Criação, guarda e revogação
- O segredo aparece uma única vez, na criação. A plataforma guarda só o prefixo visível e um HMAC do segredo.
- Revogar tem efeito imediato: a próxima requisição com a chave recebe
401 API_KEY_REVOKED. - Chaves podem ter expiração (
401 API_KEY_EXPIRED) e lista de IPs de origem (403 IP_NOT_ALLOWED). - Uma chave de um ambiente é recusada no outro: as implantações e os dados de Sandbox e produção são separados.
- Use uma chave por sistema integrado (loja, ERP, produto interno), com o menor conjunto de escopos necessário.
Escopos
Cada rota exige um escopo (indicado na referência). Faltando o escopo, a resposta é 403 SCOPE_MISSING.
| Escopo | Permite |
|---|---|
balance:read | Consultar saldo, extrato e transferências. |
checkout:write | Criar sessões de checkout. |
customers:read | Consultar clientes. |
customers:write | Cadastrar e alterar clientes. |
events:read | Consultar eventos dos últimos 30 dias. |
orders:read | Consultar pedidos. |
orders:write | Criar pedidos. |
payments:read | Consultar cobranças, operações, QR Pix, estornos, disputas, assinaturas, planos, grupos, conta e capacidades. |
payments:write | Criar cobranças e pagamentos com dois cartões. |
plans:write | Criar e alterar Pix em parcelas e parcelamento mensal. |
refunds:write | Estornar cobranças e grupos de dois cartões e enviar defesa de disputa. |
subscriptions:write | Criar, alterar, pausar, retomar e cancelar assinaturas. |
transfers:write | Cadastrar favorecidos e solicitar transferências. |
webhooks:write | Gerenciar endpoints de webhook, entregas e reenvios. |
Respostas de autenticação
| HTTP | code | Quando |
|---|---|---|
| 401 | INVALID_API_KEY | Chave ausente, malformada, desconhecida ou de outro ambiente. |
| 401 | API_KEY_REVOKED | Chave revogada. |
| 401 | API_KEY_EXPIRED | Chave expirada. |
| 403 | SCOPE_MISSING | A chave não tem o escopo da rota. |
| 403 | ACCOUNT_NOT_ALLOWED | X-Account-Id ausente ou fora das contas da chave. |
| 403 | IP_NOT_ALLOWED | Origem fora da lista de IPs da chave. |