Skip to main content
Fluxo completo para receber PIX na sua aplicação usando a API pública v1.

​
Visão geral

Permissões necessárias: payment-pix/create, payment-pix/get (opcional), webhooks/create (recomendado).

​
1. Criar a cobrança

curl -X POST https://api.goatpay.com.br/v1/payment-pix/create \
  -H "X-API-Key: gp_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "description": "Pedido #1042",
    "coverFee": false,
    "externalReference": "pedido-1042"
  }'

​
Campos importantes

CampoDescrição
amountValor em reais (decimal)
coverFeefalse = valor bruto do QR; true = líquido que você quer receber
externalReferenceID do seu pedido — use em webhooks e extrato
descriptionTexto no extrato e no QR
subaccountIdOpcional — credita subconta merchant

​
Resposta

Guarde data.id e exiba ao pagador:
  • copyPaste — string PIX
  • qrCodeBase64 — imagem PNG em base64
  • qrcodeUrl — URL da imagem
Status inicial: PENDING. Após pagamento: COMPLETED. Documentação do endpoint

​
2. Exibir no checkout

Web: decodifique qrCodeBase64 ou use qrcodeUrl em <img>. Ofereça botão “Copiar PIX” com copyPaste. Mobile: deep link para apps bancários com o copia e cola. Não feche o pedido até confirmar o pagamento (webhook ou consulta).

​
3. Confirmar pagamento

​
Recomendado: webhook

Cadastre endpoint para payment.paid. O payload traz data.externalReference e data.amount. Webhooks na prática

​
Alternativa: consulta

curl "https://api.goatpay.com.br/v1/payment-pix/get/ID_DA_COBRANCA" \
  -H "X-API-Key: gp_live_SUA_CHAVE"
Use com moderação — rate limit de 100 req/min. Polling a cada 2–5 s em muitos pedidos pode estourar o limite.

​
4. Reconciliar

FonteUso
externalReferenceLiga cobrança ao pedido no seu sistema
data.endToEndIdIdentificador PIX no SPI (suporte e MED)
GET /account/transactionsExtrato completo com todos os tipos
GET /payment-pix/listSó entradas PIX
Filtre por data, status e externalReference nas listagens.

​
Casos comuns

​
Split com parceiro

Na criação, envie splitUser (e-mail GoatPay) e splitTax (percentual do líquido).

​
Subconta merchant

Envie subaccountId no create. O líquido credita a subconta, não a conta principal. Guia de subcontas

​
QR expirado

Evento payment.pix.expired. Gere nova cobrança ou consulte status CANCELED.

​
Reembolso

Somente depósitos COMPLETED no trilho PADRAO. Use POST /refunds/create com transactionId ou e2eId. Guia PIX — reembolso

​
Erros frequentes

CódigoCausaSolução
401Chave inválidaHeader X-API-Key
403Sem permissãopayment-pix/create na chave
400Valor mínimoPADRAO: mín. R$ 3,00 na cobrança
Mais erros: Troubleshooting · Erros da API.