Autenticação
Todas as rotas /v1/* autenticam-se por chave de API:
Authorization: Bearer sk_live_...
X-API-Key: sk_live_... é aceite de forma idêntica, para os clientes HTTP que reservam
Authorization para outra coisa.
Chaves de teste e chaves reais
| Prefixo | Modo | Dinheiro real |
|---|---|---|
sk_test_… |
Teste | Não — todo o código corre (encaminhamento, comissões, validações), nenhum movimento de dinheiro |
sk_live_… |
Produção | Sim |
Os objectos criados em modo de teste levam is_test: true e nunca aparecem nos seus relatórios de
produção.
O modo de teste não cobre o pagamento instantâneo. As famílias PI e tontine recusam as chaves de teste: falam com um sistema externo que não tem ambiente de testes do nosso lado.
O segredo existe uma só vez
Ao criar (ou rodar) uma chave, o segredo é mostrado uma vez. Do lado do servidor guarda-se apenas a sua impressão HMAC: ninguém — nem o suporte — lho pode devolver. Perdido? Faça uma rotação: a chave antiga é revogada e a nova é mostrada uma vez.
Porque é que a minha chave responde client_inactive?
Uma chave é emitida logo no registo, mas não admite qualquer chamada enquanto a conta não estiver
validada (processo KYB aprovado, conta no estado active). É a porta de conformidade: abre-se com
a validação e fecha-se de imediato em caso de suspensão — a mesma chave, sem qualquer outra
alteração.
Âmbitos
Cada chave leva âmbitos, e uma operação fora do âmbito responde 403 insufficient_scope: cobrar,
pagar, reembolsar, ler, gerir os webhooks. Emita a chave mais estreita que faça o trabalho — uma
chave de leitura para os seus relatórios não precisa de poder pagar.
Idempotência
Nas criações (POST /v1/payments, POST /v1/payouts, POST /v1/refunds…), passe um cabeçalho
Idempotency-Key à sua escolha — por exemplo a sua referência de encomenda. Um reenvio com a mesma
chave devolve a operação original, nunca um duplicado; a mesma chave com um corpo diferente é
recusada com 409.
Uma chave por operação, nunca por objecto pai. Uma cobrança pode ser reembolsada em várias vezes: uma chave de idempotência com o identificador do pagamento faria o segundo reembolso parcial passar por um reenvio do primeiro. Sucesso do lado do comerciante, cliente por reembolsar.
Limite de pedidos
300 pedidos por minuto e por chave. Acima disso, 429 com um cabeçalho Retry-After — respeite-o em
vez de tentar de novo de imediato.
Boas práticas
- Uma chave por ambiente (produção, staging), nunca partilhada entre serviços.
- O segredo vive num gestor de segredos, nunca no código nem no front.
- Rotação imediata à menor dúvida — sem corte se implantar a chave nova antes de revogar a antiga.