Chaves da API
A chave da API de pagamentos autoriza as cobranças Pix de uma integração. Cada chave é de produção ou de teste e cobra só pelas ordens de cobrança escolhidas.
A chave da API é o código secreto que o seu sistema envia em cada requisição à API de pagamentos. Cada chave é de produção, que cobra compradores de verdade, ou de teste, que não cobra ninguém, e só cobra pelas ordens de cobrança escolhidas na criação. A chave aparece inteira uma única vez, logo depois de criada.
Termos da API
Antes da primeira chave, a tela mostra o card Cobre de qualquer lugar com os termos de uso, resumidos em três pontos:
- A chave é secreta: guarde só em servidor, nunca no navegador ou no app.
- Cada cobrança vale como uma venda: paga a taxa e aparece em Vendas.
- Você responde pelo uso das suas chaves.
O link Ler os termos abre o texto completo. Para continuar, marque Li e aceito os termos da API e clique em Aceitar e continuar. O aceite é feito uma vez por conta.
O card Chaves
Cada chave aparece em uma linha com:
| Elemento | O que mostra |
|---|---|
| Nome e selo | O nome da chave e o tipo, Produção ou Teste. |
| Chave | O começo e o fim da chave, com o meio oculto. |
| Escopo | Quantas ordens de cobrança a chave usa, os IPs permitidos (Qualquer IP quando não há restrição) e o teto por cobrança (Sem teto próprio quando não há). |
| Uso | Último uso, ou Nunca usada, e quantas cobranças a chave criou nas últimas 24 horas. |
| Editar, Trocar e Revogar | As ações sobre a chave, descritas abaixo. |
Sem nenhuma chave, o card mostra Nenhuma chave ainda. Crie uma de teste para começar sem cobrar ninguém. A conta tem um limite de chaves de produção, e a tela informa quantas existem sobre esse limite.
Criar uma chave
Ao clicar em Nova chave, o painel pode pedir que você entre de novo na conta para confirmar a identidade. O formulário tem os campos:
| Campo | Como funciona |
|---|---|
| Nome | Identifica a integração, com até 60 caracteres. Exemplo do campo: Servidor de produção. |
| Tipo | Produção ou Teste. A chave de teste não cobra ninguém, e os eventos dela chegam com livemode falso. O tipo não muda depois de criada. |
| Ordens de cobrança | As ordens pelas quais a chave pode cobrar. É preciso escolher ao menos uma, com Pix ativo. |
| IPs permitidos | Em Restrições (opcional). Um IP por linha, com ou sem bloco (/24, por exemplo). Vazio aceita qualquer IP. |
| Valor máximo por cobrança (R$) | Em Restrições (opcional). Vazio usa o limite da conta. Com valor, vale o menor entre ele e o limite da conta. Aceita de R$ 1,00 a R$ 1.000.000,00. |
Na chave de produção, o formulário avisa: Chave de produção cobra compradores de verdade. Clique em Criar chave. A tela Sua chave mostra a chave inteira uma vez, com o botão Copiar chave. Guarde a chave na variável de ambiente do seu servidor e clique em Já guardei.
Editar, trocar e revogar
| Ação | O que faz |
|---|---|
| Editar | Muda o nome, as ordens de cobrança e as restrições. O tipo não muda. |
| Trocar | Cria uma chave nova igual à atual. A antiga continua valendo por 1 hora, 24 horas ou 7 dias, para a integração mudar de chave sem parar. Durante esse prazo, a chave antiga mostra Vale até, com a data. |
| Revogar | Desativa a chave na hora: quem usa a chave deixa de cobrar. A ação não pode ser desfeita. |
Ordens de cobrança e prazo do Pix
O card Ordens de cobrança e prazo do PIX lista as ordens de cobrança da conta. Cada uma mostra o nome, que abre a ordem, e o ID com o botão de copiar. É esse ID, iniciado por wal_, que vai no campo wallet de cada cobrança.
Abaixo do nome, cada gateway da ordem aparece com o tempo que o comprador tem para pagar o Pix gerado por ele:
| Texto | O que significa |
|---|---|
| PIX expira em, seguido do prazo | O prazo configurado no gateway. |
| PIX expira em, seguido de dias, com (esta gateway arredonda o prazo para dias) | O gateway só aceita prazos em dias. |
| Prazo definido pela própria gateway; o valor configurado só aparece para o comprador | Quem define o vencimento é o gateway. O prazo configurado no ggCheckout aparece para o comprador, mas não muda o vencimento. |
| Sem PIX nesta ordem de cobrança | A ordem não tem gateway de Pix. |
O lápis ao lado do prazo abre a configuração do gateway, onde o prazo do Pix é alterado. Sem nenhuma ordem, o card leva a Gateways › Ordem de cobrança para criar uma, como descreve Ordem de cobrança.
Quando uma ordem usada pela API é excluída, a integração que envia o ID dela passa a receber erro. As cobranças já criadas nessa ordem saem do alcance da chave: ela não consulta, não lista e não cancela mais essas cobranças.
No painel
Ferramentas > Gateways > API de pagamentos.
Páginas relacionadas
- Primeira cobrança Pix: a primeira requisição com a chave de teste.
- Modo de teste: o que a chave de teste simula.
- Ordem de cobrança: a sequência de gateways que gera o Pix.