Skip to main content
API PIX da GoatPay em três blocos. Cada um exige permissões na chave (payment-pix/*, refunds/*, transfer-pix/*).
BlocoPrefixoUso
Receber/payment-pix/*Gerar QR / copia e cola; o pagador envia PIX para você
Reembolsar/refunds/*Devolver um depósito PIX já recebido
Enviar/transfer-pix/*Debitar sua conta e enviar para chave PIX ou BR Code
/payouts/* é alias de /transfer-pix/* (permissões payouts/*).

​
Status (data.status)

Válido em consultas e listagens de cobrança, transferência e reembolso:
StatusSignificado
PENDINGAguardando pagamento ou processamento
PROCESSINGEm processamento no SPI
COMPLETEDConcluído com sucesso
FAILEDFalhou ou foi rejeitado
CANCELEDCancelado ou QR expirado
REVERSEDEstorno concluído
Na resposta de criar cobrança, o status inicial costuma ser PENDING. Após o pagamento, COMPLETED.

​
coverFee (como informar o valor)

Controla o que o campo amount representa:
OperaçãocoverFee: falsecoverFee: true
Cobrança (payment-pix)Valor bruto do QR (padrão)Valor líquido que você quer receber
Transferência (transfer-pix)Valor debitado da sua contaValor recebido pelo destinatário (padrão)
Detalhes nos bodies de criar cobrança e criar transferência.

​
Receber PIX

1

Criar cobrança

POST /payment-pix/create — amount, description e opcionais (coverFee, pagador, split, externalReference).Resposta: id, status, copyPaste, qrCodeBase64, qrcodeUrl.Criar cobrança
2

Exibir QR

Mostre copyPaste, qrCodeBase64 ou qrcodeUrl no checkout.
3

Acompanhar

GET /payment-pix/get/{id} ou GET /payment-pix/list. Webhooks: payment.created, payment.paid.Consultar · Listar
Para creditar o líquido em uma subconta merchant, envie subaccountId no mesmo POST /payment-pix/create (não há rota PIX exclusiva de subconta). Saques com saldo da subconta usam subaccountId em POST /transfer-pix/create. Veja o guia de subcontas.

​
Reembolsar depósito

Somente depósitos COMPLETED com endToEndId, no trilho PADRÃO da chave.
1

Solicitar

POST /refunds/create — transactionId ou e2eId; opcional refundId, nature, description. Estorno integral.Solicitar reembolso
2

Acompanhar

GET /refunds/get/{id} ou GET /refunds/list. Webhooks: refund.requested, refund.completed, refund.failed.Consultar · Listar
Reembolso não está disponível no trilho LIVRE nem sem endToEndId.

​
Enviar PIX

1

Destino

Chave (pixKey + pixKeyType: CPF, CNPJ, EMAIL, TELEFONE, CHAVE_ALEATORIA) ou BR Code (pixCopyPaste).pixKeyOwnerDocument (CPF ou CNPJ do titular da chave) é opcional/legado e não é mais necessário para transferir por chave PIX.
2

Criar

POST /transfer-pix/create — amount, description, destino.Criar transferência
3

Acompanhar

GET /transfer-pix/get/{id} ou GET /transfer-pix/list. Webhooks: transfer.created, transfer.completed.Consultar · Listar
pixCopyPaste (pagar QR de terceiro) exige trilho PADRÃO na API key.

​
Quando enviar (programadas)

Para agendar, repetir ou enviar ao atingir saldo, use transfer-scheduled/* em vez de criar a transferência imediata:
triggerTypeUso
ONCEData/hora única (scheduledAt)
RECURRINGDiária, semanal, mensal ou intervalo (recurrenceRule)
BALANCE_THRESHOLDQuando saldo ≥ balanceThreshold
O objeto payload aceita PIX, transferência interna ou cripto — guia completo.

​
Split na cobrança (opcional)

  • splitUser — e-mail da conta GoatPay parceira
  • splitTax — percentual do líquido (0,01 a 100)

​
Listagens

Query params em GET /payment-pix/list e GET /transfer-pix/list:
ParâmetroDescrição
page / pageSizePaginação (padrão 1 / 50, máx. 100)
dateFrom / dateToPeríodo (createdAt, ISO 8601)
statusVer tabela de status acima
externalReferenceFiltro exato
searchBusca em id, descrição, referência, E2E, referenceId, chave PIX
{
  "items": [],
  "page": 1,
  "pageSize": 50,
  "total": 120,
  "pages": 3
}
Extrato completo: GET /account/transactions (guia Conta).

​
Endpoints

Criar cobrança

QR para receber.

Consultar cobrança

Objeto completo em data.

Listar cobranças

Só entradas PIX.

Reembolso

Devolver depósito.

Enviar PIX

Chave ou BR Code.

Consultar envio

Status da transferência.

Listar envios

Só saídas PIX.