API de pagamentos
A API de pagamentos cobra por Pix a partir do seu servidor, bot ou automação, pelos gateways de uma ordem de cobrança, e avisa o pagamento por webhook.
A API de pagamentos do ggCheckout cria cobranças por Pix a partir do seu servidor, de um bot ou de uma automação, sem passar pelo checkout. Cada cobrança usa os gateways de Pix de uma ordem de cobrança da sua conta, e as credenciais desses gateways não saem do ggCheckout. A API cobra só por Pix. Cada cobrança vale como uma venda: paga a taxa do ggCheckout e aparece em Pagamentos.
Como funciona
- Em Ferramentas > Gateways > API de pagamentos, você aceita os termos da API e cria uma chave, descrita em Chaves da API.
- Na mesma tela, você copia o ID da ordem de cobrança que vai cobrar. O ID começa com
wal_. - O seu sistema cria a cobrança com
POST /v1/payment_intents, informando o valor, os dados do comprador e o ID da ordem. A resposta traz o Pix copia e cola e o QR Code. - Um webhook de origem API avisa o seu sistema quando o Pix é pago, vence ou falha.
A cobrança segue a ordem de cobrança: a plataforma principal da lista PIX gera o Pix e, se falhar, a próxima reserva tenta. O prazo que o comprador tem para pagar é o configurado em cada gateway da ordem.
O básico da API
| Item | Como é |
|---|---|
| Endereço | https://api.ggcheckout.app/v1 |
| Autenticação | Header Authorization: Bearer seguido da chave. Chave de produção começa com ggpk_live_; chave de teste, com ggpk_test_. |
| Valores | Centavos inteiros, em reais. 4990 é R$ 49,90. |
| Datas | ISO 8601, em UTC. |
| IDs | Com prefixo: pi_ é a cobrança, wal_ é a ordem de cobrança e evt_ é o evento de webhook. |
| Criação de cobrança | Exige o header Idempotency-Key, descrito em Idempotência. |
A chave é secreta. Ela fica só no servidor, em uma variável de ambiente como GG_PAYMENTS_API_KEY, e não vai em código que roda no navegador ou em aplicativo instalado no celular.
A cobrança como venda
A cobrança paga pela API aparece em Pagamentos, e o filtro Origem separa as vendas do Checkout das vendas da API. A taxa do ggCheckout é a mesma de uma venda feita no checkout. As cobranças criadas com chave de teste não aparecem em Pagamentos e não cobram ninguém, como descreve Modo de teste.
No painel
Ferramentas > Gateways > API de pagamentos. A tela tem os cards Chaves, Ordens de cobrança e prazo do PIX e Integre em minutos. O último traz o botão Integrar com IA, descrito em Usando IA com o ggCheckout, e o link Abrir a documentação.
Chaves da API
Termos, criação, troca e revogação das chaves, e os IDs das ordens de cobrança.
Primeira cobrança Pix
Da chave de teste ao Pix na tela do comprador.
Webhooks da API
Os eventos da cobrança, o formato da entrega e a assinatura.
Idempotência
Como repetir um pedido sem criar uma segunda cobrança.
Modo de teste
Os cenários simulados e os limites da chave de teste.
Erros e limites
O formato dos erros, os códigos e os limites de requisição.
Referência da API
As rotas, os parâmetros e as respostas.
Ferramentas avançadas
Os recursos do ggCheckout para quem programa ou automatiza: a API de pagamentos, o servidor MCP, o uso de IA e a limpeza de cache.
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.