Autenticação e permissões
Chaves de API, modo teste e produção, permissões por recurso e IPs permitidos.
Toda chamada leva a sua chave de API, de um destes dois jeitos:
# No header x-api-key
curl https://api.wysepay.com.br/api/v1/balance \
-H "x-api-key: wyp_test_sua_chave"
# Ou como Bearer
curl https://api.wysepay.com.br/api/v1/balance \
-H "Authorization: Bearer wyp_test_sua_chave"Sem a chave, ou com uma chave revogada, a resposta é 401.
Teste e produção
O modo é definido pela chave, não pelo endereço: as duas usam https://api.wysepay.com.br.
| Chave de teste | Chave de produção | |
|---|---|---|
| Começa com | wyp_test_ | wyp_ |
| Dinheiro real | Nunca | Sim |
| Precisa de conta verificada | Não | Sim |
| Pagamentos e saques | Simulados | Reais |
| Webhooks | Só para endpoints de teste | Só para endpoints de produção |
livemode nas respostas | false | true |
Os dados de teste ficam separados dos reais: uma chave de teste não enxerga cobranças, clientes ou saques de produção, e o contrário também vale.
Criar uma chave
- No painel, vá em Desenvolvedores → Chaves de API.
- Para uma chave de teste, ligue antes o Modo teste no topo da tela.
- Dê um nome que diga onde ela será usada (ex.: "Servidor da loja"), escolha as permissões e, se quiser, os IPs.
- Clique em Criar chave e copie na hora: ela aparece uma única vez.
Chaves de produção só podem ser criadas depois que a conta é verificada. Veja Criar conta e liberar produção.
Permissões
Cada chave tem permissões por recurso. Dê a cada sistema só o que ele usa: um painel de BI, por exemplo, só precisa ler.
| Recurso | Ler | Criar e alterar |
|---|---|---|
| Cobranças Pix | charges:write | |
| Transações | transactions:read | |
| Links de pagamento | payment_links:read | payment_links:write |
| Clientes | customers:read | customers:write |
| Saldo | balance:read | |
| Saques | withdrawals:read | withdrawals:write |
- Chaves novas vêm com tudo, menos
withdrawals:write(sacar). - Chaves criadas antes das permissões ficaram com tudo, menos sacar: as integrações continuam funcionando.
- Mudar as permissões vale na hora: em Chaves de API, clique no ícone de ajustes da chave.
Sem a permissão da rota, a resposta é 403 com code: "API_KEY_PERMISSION", dizendo qual falta. A permissão de cada rota aparece na referência.
IPs permitidos
Você pode limitar a chave aos IPs do seu servidor. Com a lista preenchida, uma chamada de outro IP responde 403 com code: "API_KEY_IP", mesmo com a chave certa.
- Um IP por linha, IPv4 ou IPv6.
- Faixas em CIDR:
203.0.113.0/24libera de203.0.113.0a203.0.113.255. - Lista vazia: qualquer IP.
Recomendado para chaves que sacam
Uma chave com withdrawals:write tira dinheiro da conta. Libere só o IP do servidor que a usa e defina um limite diário. Veja Saques.
Guarde a chave no servidor
Nunca coloque a chave no navegador ou no app
Quem tem a chave age em nome da sua conta, dentro das permissões dela. A chave deve ficar só no seu servidor, numa variável de ambiente, nunca no código do site, do aplicativo ou num repositório.
Se uma chave vazar, revogue em Chaves de API e crie outra. A chave revogada para de funcionar na hora.