GG CheckoutCentral de Ajuda

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

POST/v1/payment_intents
curl 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()

Campo

Tipo

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:

GET/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

statusO que significa
processingO PIX ainda está sendo gerado. Aparece depois de um 502: repita o pedido com a mesma Idempotency-Key
requires_actionPIX gerado, esperando o pagamento
succeededPago
expiredO QR venceu sem pagamento, ou a cobrança ficou 2 horas sem uso
canceledVocê cancelou antes do pagamento
failedNenhum 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

POST/v1/payment_intents/{id}/cancel
curl -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.

Nesta página