Autenticação
Como enviar a chave de API, o que acontece quando ela falha e como mantê-la segura.
Toda chamada à API é autenticada por uma chave de API enviada no cabeçalho Authorization. A chave identifica a sua conta: a API descobre a qual conta a cobrança pertence a partir dela, e por isso nenhum identificador de conta vai no corpo.
Authorization: kpa_test_sk_9f2c...
Content-Type: application/jsonEnvie a chave crua, como acima. Não acrescente Bearer, Basic nem outro prefixo.
A chave basta para todas as rotas desta documentação, inclusive saldo, saques e extrato. Não há fluxo de login, OAuth ou troca por token de acesso.
A chave dá acesso a cobrar, estornar e sacar em nome da sua conta. Guarde-a no cofre de segredos do seu servidor, nunca em código-fonte, em app, em navegador ou em log. Se ela vazar, peça a revogação imediata à equipe de integração.
Formato da chave
| Ambiente | Prefixo |
|---|---|
| Sandbox | kpa_test_sk_ |
| Produção | kpa_live_sk_ |
O prefixo serve para você conferir, antes da chamada, se está usando a chave do ambiente certo. Um teste comum na sua configuração: recusar a inicialização do serviço em produção se a chave começar com kpa_test_.
Permissões
Cada chave tem permissões por operação. A equipe de integração concede as permissões de acordo com o que foi contratado; peça só as que a sua integração usa. Uma chamada sem a permissão recebe 403.
| Operação | Permissão |
|---|---|
| Criar cobrança, pedir estorno | paymentintents:create |
| Consultar cobrança | paymentintents:read |
| Pré-análise do Pix parcelado | pagaleve:create |
| Abrir sessão 3DS | 3ds:create |
| Abrir sessão do SDK de campos | card-token-sessions:create |
| Salvar cartão (tokenização) | card-tokens:create |
| Consultar saldo | balance:read |
| Solicitar e cancelar saque | withdrawals:create |
| Consultar e listar saques | withdrawals:read |
| Consultar extrato | bank-accounts:read |
Se você opera doméstico e offshore, cada operação tem a sua chave, e cada chave precisa das próprias permissões. Veja Contas, chaves e identificadores.
Lista de IPs permitidos
A sua conta pode restringir o saldo e os saques a uma lista de IPs de saída. Com a lista ativa, a chamada só passa se vier de um IP cadastrado; senão, a resposta é 403 com type: ip_not_allowed.
- Vale o IP público de onde a conexão do seu servidor chega à Accelerazione, depois do seu NAT ou proxy de saída. Não é o IP interno da máquina.
- Cabeçalhos não escolhem o IP.
X-Forwarded-ForouX-Client-Ipenviados por você são ignorados ou sobrescritos pela borda da API. Não há como declarar outra origem. - A lista é por conta, independente da chave: trocar de chave não muda a lista.
- Informe à equipe de integração todos os IPs de saída, inclusive os de contingência, antes de trocar de provedor de nuvem ou de NAT. Mudanças levam até um minuto para valer.
- Se a lista não puder ser conferida naquele momento, a resposta é
503 ip_allowlist_unavailable. Repita em alguns segundos.
Respostas de autenticação
Os erros de autenticação são respondidos pela borda da API, antes de a requisição chegar ao serviço. Por isso o corpo tem um formato próprio, com um único campo message, diferente dos erros de aplicação.
| HTTP | Corpo | Causa | O que fazer |
|---|---|---|---|
401 | {"message":"Unauthorized"} | O cabeçalho Authorization não foi enviado. | Confira se o seu cliente HTTP envia o cabeçalho em todas as chamadas, inclusive nas repetições. |
403 | {"message":"Forbidden"} | A chave não tem permissão para o recurso, ou o IP de origem não está na lista permitida. | Confira a rota e o ambiente. Persistindo, peça a permissão à equipe de integração. |
500 | {"message":"Internal Server Error"} | Chave inválida, expirada ou revogada. | Veja o aviso abaixo. |
Chave inválida responde 500
Hoje, uma chave inexistente, expirada ou revogada recebe 500 com o corpo {"message":"Internal Server Error"}, e não 401. Se todas as chamadas de um ambiente começarem a responder 500 com esse corpo exato, confira primeiro a chave e o ambiente antes de tratar como indisponibilidade da Accelerazione.
Depois de um 403 por falta de permissão, outras rotas da mesma chave podem responder 403 por até 60 segundos. Corrigida a permissão, aguarde esse intervalo antes de concluir que a correção não funcionou.
Rastreamento
Respostas da API de cobranças trazem o cabeçalho X-Request-Id (formato req_ seguido de 32 caracteres hexadecimais). Registre esse valor nos seus logs junto com o id do PaymentIntent: com ele a equipe de integração encontra a sua requisição sem depender de horário aproximado.
Você também pode enviar um X-Correlation-Id próprio para amarrar a chamada ao seu rastreamento. Quando válido, ele volta igual na resposta.
Ambientes e endereços
As superfícies da API (API, Hooks e SDKs), os endereços de sandbox e de produção, e as diferenças entre os dois ambientes.
Integre com agentes de IA
Como apontar Claude, ChatGPT, Cursor ou qualquer assistente de código para esta documentação, e as regras que ele precisa seguir para gerar uma integração segura.