Skip to main content
Este guia leva você da conta GoatPay até a primeira cobrança PIX confirmada por webhook. Tempo estimado: 15–20 minutos.

​
Pré-requisitos

  • Conta em app.goatpay.com.br
  • Backend ou ferramenta que faça HTTP (curl, Postman, seu servidor)
  • URL HTTPS pública para webhooks (em dev, use ngrok ou similar)

​
1. Criar a chave de API

  1. Acesse Integrações → Chaves de API
  2. Clique em Nova chave
  3. Preencha:
    • Descrição: ex. Produção ERP
    • Preset: comece com read + adicione payment-pix/create e webhooks/create, ou use write
    • Trilho: PADRAO (único trilho operacional)
  4. Copie o gp_live_... — ele aparece uma única vez
Guarde em variável de ambiente: 
export GOATPAY_API_KEY=gp_live_SUA_CHAVE
Não existe sandbox separado. Todas as chaves são de produção; teste com valores baixos (ex. R$ 1,00).
Detalhes de permissões: Permissões da API key · Chaves de API.

​
2. Testar autenticação

curl https://api.goatpay.com.br/v1/account/balance \
  -H "X-API-Key: $GOATPAY_API_KEY"
Resposta esperada (envelope padrão): 
{
  "success": true,
  "message": "OK",
  "data": {
    "currency": "BRL",
    "availableAmount": 0,
    "pendingAmount": 0
  },
  "requestId": "req_..."
}
Se receber 401, confira o header X-API-Key. Se 403, ajuste permissões ou IP allowlist no dashboard.

​
3. Criar uma cobrança PIX

curl -X POST https://api.goatpay.com.br/v1/payment-pix/create \
  -H "X-API-Key: $GOATPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1,
    "description": "Teste integração",
    "coverFee": false,
    "externalReference": "pedido-001"
  }'
Na resposta, use:
CampoUso
data.idConsultar status depois
data.copyPastePix copia e cola no checkout
data.qrCodeBase64QR em base64
data.qrcodeUrlURL da imagem do QR
Mostre o QR ou o copia e cola para o pagador. Guia completo: Receber PIX.

​
4. Cadastrar webhook

curl -X POST https://api.goatpay.com.br/v1/webhooks/create \
  -H "X-API-Key: $GOATPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.suaempresa.com/goatpay/webhook",
    "events": ["payment.paid", "payment.created", "payment.pix.expired"]
  }'
Anote o whsec_... retornado — só aparece na criação. Guia passo a passo: Webhooks na prática.
Endpoints criados por API key só recebem eventos de transações criadas pela mesma chave.

​
5. Confirmar o pagamento

Após o pagador concluir o PIX:
  1. Sua URL recebe POST com evento payment.paid
  2. Valide x-goatpay-signature com o whsec_...
  3. Use data.externalReference para marcar o pedido como pago no seu sistema
Alternativa sem webhook: GET /v1/payment-pix/get/{id} — mas prefira webhooks em produção.

​
Checklist de produção

  • Chave com permissões mínimas (não use full sem necessidade)
  • GOATPAY_API_KEY em secret manager, nunca no repositório
  • Webhook com HTTPS e validação HMAC
  • Idempotência pelo id da entrega webhook
  • externalReference em toda cobrança para reconciliação
  • Tratamento de 429 (100 req/min por chave)

​
Próximos passos

Receber PIX

Fluxo completo de cobrança e reconciliação.

Webhooks

Código de validação HMAC e idempotência.

Integração com IA

Use llms.txt no Cursor, Claude ou ChatGPT.

API Reference

Todas as rotas e playground interativo.