Receber PIX

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

Campo	Descrição
`amount`	Valor em reais (decimal)
`coverFee`	`false` = valor bruto do QR; `true` = líquido que você quer receber
`externalReference`	ID do seu pedido — use em webhooks e extrato
`description`	Texto no extrato e no QR
`expirationSeconds`	Validade do QR em segundos (padrão `86400` = 24 h)
`subaccountId`	Opcional — credita subconta merchant

Resposta

Guarde data.id e exiba ao pagador:

copyPaste — string PIX
qrCodeBase64 — imagem PNG em base64 (somente na resposta do create)
qrcodeUrl — URL da imagem
expiresAt — data/hora de expiração do QR (ISO 8601)

Webhooks payment.created não incluem QR. Desde 15/08/2026, GET /payment-pix/get pendente retorna copyPaste e qrcodeUrl, mas não qrCodeBase64.

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 de status

Para polling, use a rota enxuta de status (sem QR Code nem copia e cola):

curl "https://api.goatpay.com.br/v1/payment-pix/status/ID_DA_COBRANCA" \
  -H "X-API-Key: gp_live_SUA_CHAVE"

A rota status retorna apenas id, status, valores e datas — ideal para verificar pagamento a cada 2–5 s. Para QR, pagador e demais detalhes, use GET /payment-pix/get/{id}. Consultar status · Consultar cobrança completa 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

Fonte	Uso
`externalReference`	Liga cobrança ao pedido no seu sistema
`data.endToEndId`	Identificador PIX no SPI (suporte e MED)
`GET /account/transactions`	Extrato completo com todos os tipos
`GET /payment-pix/list`	Só 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ódigo	Causa	Solução
401	Chave inválida	Header `X-API-Key`
403	Sem permissão	`payment-pix/create` na chave
400	Valor mínimo	PADRAO: mín. R$ 1,00 na cobrança

Mais erros: Troubleshooting · Erros da API.

Começar

Integração

Tutoriais

Ajuda

Visão geral

1. Criar a cobrança

Campos importantes

Resposta

2. Exibir no checkout

3. Confirmar pagamento

Recomendado: webhook

Alternativa: consulta de status

4. Reconciliar

Casos comuns

Split com parceiro

Subconta merchant

QR expirado

Reembolso

Erros frequentes

​Visão geral

​1. Criar a cobrança

​Campos importantes

​Resposta

​2. Exibir no checkout

​3. Confirmar pagamento

​Recomendado: webhook

​Alternativa: consulta de status

​4. Reconciliar

​Casos comuns

​Split com parceiro

​Subconta merchant

​QR expirado

​Reembolso

​Erros frequentes

Visão geral

1. Criar a cobrança

Campos importantes

Resposta

2. Exibir no checkout

3. Confirmar pagamento

Recomendado: webhook

Alternativa: consulta de status

4. Reconciliar

Casos comuns

Split com parceiro

Subconta merchant

QR expirado

Reembolso

Erros frequentes