Primeira cobrança Pix
Os passos da primeira cobrança Pix pela API de pagamentos: chave de teste, ID da ordem de cobrança, criação da cobrança, Pix na tela e aviso de pagamento.
Antes de começar
Crie uma chave de teste
Em Minha carteira → API, aceite os termos e crie uma chave. Use uma chave de teste (ggpk_test_…) enquanto integra: ela não cobra ninguém. Escolha quais carteiras a chave pode usar.
Copie o id da carteira
O id wal_… aparece na mesma tela. Você também pode listar as carteiras da chave com GET /v1/wallets.
Guarde a chave numa variável de ambiente
Por exemplo GG_PAYMENTS_API_KEY. A chave só aparece uma vez, na criação.
Criar a cobrança
/v1/payment_intentscurl https://api.ggcheckout.app/v1/payment_intents \
-H "Authorization: Bearer $GG_PAYMENTS_API_KEY" \
-H "Idempotency-Key: pedido-1234" \
-H "Content-Type: application/json" \
-d '{
"wallet": "wal_8f3kQ2",
"amount": 4990,
"description": "Mentoria individual",
"external_reference": "pedido-1234",
"buyer": {
"name": "Maria Souza",
"email": "maria@exemplo.com",
"document": "123.456.789-09",
"phone": "11987654321"
}
}'const response = await fetch('https://api.ggcheckout.app/v1/payment_intents', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GG_PAYMENTS_API_KEY}`,
'Idempotency-Key': 'pedido-1234',
'Content-Type': 'application/json',
},
body: JSON.stringify({
wallet: 'wal_8f3kQ2',
amount: 4990,
description: 'Mentoria individual',
external_reference: 'pedido-1234',
buyer: {
name: 'Maria Souza',
email: 'maria@exemplo.com',
document: '123.456.789-09',
phone: '11987654321',
},
}),
});
const intent = await response.json();import os
import requests
response = requests.post(
"https://api.ggcheckout.app/v1/payment_intents",
headers={
"Authorization": f"Bearer {os.environ['GG_PAYMENTS_API_KEY']}",
"Idempotency-Key": "pedido-1234",
},
json={
"wallet": "wal_8f3kQ2",
"amount": 4990,
"description": "Mentoria individual",
"external_reference": "pedido-1234",
"buyer": {
"name": "Maria Souza",
"email": "maria@exemplo.com",
"document": "123.456.789-09",
"phone": "11987654321",
},
},
)
intent = response.json()Prop
Type
Idempotency-Key é obrigatório. Veja Idempotência.
A resposta
{
"id": "pi_3Hk9…",
"object": "payment_intent",
"livemode": true,
"status": "requires_action",
"amount": 4990,
"wallet": "wal_8f3kQ2",
"external_reference": "pedido-1234",
"pix": {
"copy_paste": "00020126…",
"qr_base64": "iVBORw0KGgo…",
"expires_at": "2026-10-19T15:30:00.000Z"
},
"created_at": "2026-10-19T15:00:00.000Z",
"expires_at": "2026-10-19T17:00:00.000Z"
}Mostre ao comprador o pix.copy_paste (copia e cola) ou o QR (pix.qr_base64, uma imagem PNG em base64). pix.expires_at é o prazo do QR: ele vem do gateway que gerou o PIX e segue o prazo configurado nessa credencial.
Nas consultas, os dados do comprador voltam mascarados: CPF como ***.456.789-**, e-mail parcial e só os quatro últimos dígitos do telefone.
Saber se foi pago
Cadastre um webhook com origem API e receba payment_intent.succeeded. Veja Webhooks.
Se preferir consultar:
/v1/payment_intents/{id}Para listar, use GET /v1/payment_intents com os filtros status, external_reference e created_gte (Unix, em segundos). A lista vem em páginas de até 100: passe o next_cursor da resposta em starting_after para pegar a próxima.
Estados
status | O que significa |
|---|---|
processing | O PIX ainda está sendo gerado. Aparece depois de um 502: repita o pedido com a mesma Idempotency-Key |
requires_action | PIX gerado, esperando o pagamento |
succeeded | Pago |
expired | O QR venceu sem pagamento, ou a cobrança ficou 2 horas sem uso |
canceled | Você cancelou antes do pagamento |
failed | Nenhum gateway da carteira conseguiu gerar o PIX |
Uma cobrança que nunca foi usada vence em 2 horas. Crie a cobrança na hora em que o comprador for pagar.
Cancelar
/v1/payment_intents/{id}/cancelcurl -X POST https://api.ggcheckout.app/v1/payment_intents/pi_3Hk9…/cancel \
-H "Authorization: Bearer $GG_PAYMENTS_API_KEY"Dá para cancelar enquanto a cobrança não foi paga, não falhou e não venceu. Cancelar de novo uma cobrança já cancelada não muda nada.
PIX pago depois do cancelamento
Se o comprador pagar um PIX depois que você cancelou, o dinheiro entra do mesmo jeito. Nesse caso você recebe payment_intent.succeeded_after_cancel para decidir o que fazer.
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.
Webhooks da API
O webhook de origem API avisa o seu sistema quando a cobrança Pix é gerada, paga, vence, falha ou é cancelada. Cada entrega vem assinada com HMAC.