Guia de integração PIX

API PIX da GoatPay em três blocos. Cada um exige permissões na chave (payment-pix/*, refunds/*, transfer-pix/*).

Bloco	Prefixo	Uso
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:

Status	Significado
`PENDING`	Aguardando pagamento ou processamento
`PROCESSING`	Em processamento no SPI
`COMPLETED`	Concluído com sucesso
`FAILED`	Falhou ou foi rejeitado
`CANCELED`	Cancelado ou QR expirado
`REVERSED`	Estorno 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ção	`coverFee: false`	`coverFee: 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 conta	Valor recebido pelo destinatário (padrão)

Detalhes nos bodies de criar cobrança e criar transferência.

`emitFiscalInvoice` (nota fiscal no depósito)

Com emissão fiscal automática configurada no dashboard (plugin de nota fiscal), envie emitFiscalInvoice: true em POST /payment-pix/create para gerar a nota fiscal quando o PIX for confirmado. O campo é opcional e o padrão é false. No dashboard, a mesma opção aparece na tela de depósito PIX.

`expirationSeconds` (validade do QR Code)

Tempo de expiração do QR Code PIX em segundos. Padrão: 86400 (24 horas). Mínimo 60, máximo 604800 (7 dias). Na resposta, expiresAt (ISO 8601) indica quando o QR deixa de aceitar pagamento. Use esse campo para contagem regressiva no checkout.

Receber PIX

Criar cobrança

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

Exibir QR

Mostre copyPaste, qrCodeBase64 ou qrcodeUrl da resposta do create. Use expiresAt para exibir contagem regressiva.

Desde 15/08/2026, GET /payment-pix/get pendente retorna copyPaste e qrcodeUrl, mas não qrCodeBase64. Webhooks payment.created também não incluem QR — persista a resposta do create.

Acompanhar

GET /payment-pix/status/{id} para polling (payload enxuto) ou GET /payment-pix/get/{id} para detalhes completos. Webhooks: payment.created, payment.paid.Consultar status · Consultar cobrança · 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.

Solicitar

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

Acompanhar

GET /refunds/get/{id} ou GET /refunds/list. Webhooks: refund.requested, refund.completed, refund.failed.Consultar · Listar

Reembolso exige endToEndId do depósito original.

Enviar PIX

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.

Criar

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

Acompanhar

GET /transfer-pix/status/{id} para polling (payload enxuto) ou GET /transfer-pix/get/{id} para detalhes completos. Webhooks: transfer.created, transfer.completed.Consultar status · Consultar transferência · Listar

pixCopyPaste (pagar QR de terceiro) exige trilho PADRÃO na API key.

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âmetro	Descrição
`page` / `pageSize`	Paginação (padrão 1 / 50, máx. 100)
`dateFrom` / `dateTo`	Período (`createdAt`, ISO 8601)
`status`	Ver tabela de status acima
`externalReference`	Filtro exato
`search`	Busca em id, descrição, referência, E2E, `referenceId`, chave PIX
`subaccountId` / `merchantSubaccountId`	Filtra cobranças ou transferências vinculadas à subconta merchant

{
  "items": [],
  "page": 1,
  "pageSize": 50,
  "total": 120,
  "pages": 3
}

Extrato completo: GET /account/transactions (guia Conta).

Transferências programadas

Programações de transferência permitem definir quando enviar sem chamar transfer-pix/create a cada execução. O painel e a API usam o mesmo modelo. Permissões: transfer-scheduled/create, get, list, update, cancel, run-now.

Tipos de disparo (`triggerType`)

Valor	Uso	Campos obrigatórios
`ONCE`	Uma vez em data/hora	`scheduledAt` (ISO 8601, futuro)
`RECURRING`	Repetição	`recurrenceRule`
`BALANCE_THRESHOLD`	Ao atingir saldo	`balanceThreshold` (reais)

Payload da transferência

O objeto payload descreve o que enviar (igual ao formulário Transferir do dashboard):

`method`	Destino
`pix_padrao`	`pixKey`, `pixKeyType`, opcional `subaccountId`
`interna`	`recipientEmail` (conta GoatPay)
`cripto`	`address`, `payCurrency`, opcional `extraId`

Sempre inclua amount e, se quiser, description e coverFee.

Recorrência (`recurrenceRule`)

Campo	Descrição
`interval`	`daily`, `weekly`, `monthly`, `custom_days`
`time`	Horário local, ex. `09:00`
`timezone`	Padrão `America/Sao_Paulo`
`dayOfWeek`	0–6 (semanal)
`dayOfMonth`	1–31 (mensal)
`customDays`	Intervalo em dias

Opcional: maxRuns limita quantas vezes a recorrência executa.

Fluxo recomendado

1. Criar programação

POST /transfer-scheduled/create com triggerType, payload e parâmetros de agenda.Criar programação

2. Acompanhar

Listar ou consultar por id.

3. Gerenciar

Pausar/retomar · Cancelar · Executar agora

Campos na resposta (`data`)

Cada programação retorna:

Campo	Descrição
`id`	ID da programação
`label`	Rótulo ou texto gerado
`amount`	Valor do `payload`
`method`	Tipo legível (PIX Padrão, Interna, Cripto…)
`destination`	Destino mascarado
`triggerType`	`once`, `recurring` ou `balance_threshold`
`scheduleLabel`	Regra em linguagem natural
`nextRunAt`	Próxima execução (ISO) ou `—`
`lastRunAt`	Última execução, se houver
`runCount`	Execuções já realizadas
`status`	`active`, `paused`, `completed`, `failed`
`coverFee`	Taxa absorvida pelo remetente

GET /transfer-scheduled/list retorna { items: [...] } em data.

Limite de 20 programações ativas por conta. Transferências imediatas continuam em POST /transfer-pix/create (ou interna/cripto).

Disputas MED

Disputas MED no trilho PADRAO (PIX regulado). A API key precisa das permissões meds/list, meds/get e meds/evidence.

Fluxo típico

1. Webhook med.created

Quando uma disputa abre, a GoatPay envia med.created (configure em Webhooks).

2. Listar ou consultar

Use Listar ou Consultar pelo id ou protocol.

3. Enviar defesa

Enquanto status for OPEN, envie Evidências com justificativa e comprovantes — exceto se a contestação automática estiver ativa na conta (padrão), caso em que a API retorna 403 e a GoatPay responde sozinha.

4. Resultado

Após análise: ACCEPTED, REJECTED, CANCELED ou EXPIRED. Eventos med.resolved / med.evidence_sent via webhook.

Status da disputa

Status	Significado
`OPEN`	Aberta — aceita envio de evidências
`UNDER_REVIEW`	Defesa enviada, aguardando análise
`ACCEPTED`	Disputa aceita (valor não retorna ao disponível)
`REJECTED`	Rejeitada a favor do recebedor
`CANCELED`	Cancelada
`EXPIRED`	Expirada

Saldo e trilho

MED em PIX creditado na conta principal bloqueia availablePadrao e blockedAmount da main.
MED em PIX creditado em subconta (subaccountId na cobrança) bloqueia saldo da subconta (availablePadrao → lockedPadrao), sem debitar a main.
Saques cripto no PADRAO podem ser bloqueados enquanto houver MED OPEN ou UNDER_REVIEW na conta.

Detalhes de subcontas: guia de subcontas.

Enviar evidências

Enquanto status for OPEN:

Campo	Regra
`justification`	Obrigatório (10–2000 caracteres)
`proofs`	Até 10 URLs públicas; pode ser obrigatório conforme o tipo de disputa
`analysis`	`aceito` ou `rejeitado`; obrigatório em alguns fluxos, ignorado em outros
`files`	Multipart: até 5 arquivos (PDF/JPG/PNG/WEBP, máx. 5 MB cada) quando suportado

Envie JSON (application/json) ou multipart/form-data com os mesmos campos. Detalhes em Enviar evidências.

Contestação automática (ativa por padrão): disputas acima de R$ 50 recebem defesa gerada pela GoatPay. Enquanto estiver ativa, o merchant não pode enviar evidências manualmente — POST /meds/{id}/evidence responde 403. Desative no dashboard em Disputas ou peça ao suporte.

Disputas de seed local em desenvolvimento não aceitam defesa real. Use MED aberta pelo fluxo de produção.

Filtros em `GET /meds/list`

Parâmetro	Descrição
`page` / `pageSize`	Paginação (máx. 100 por página)
`dateFrom` / `dateTo`	Período em `openedAt` (ISO 8601)
`status`	`OPEN`, `UNDER_REVIEW`, `ACCEPTED`, `REJECTED`, `CANCELED`, `EXPIRED`
`search`	Busca em `id`, `protocol`, `transactionId`, `infractionId`

PIX automático

O PIX automático permite cobranças recorrentes com consentimento explícito do pagador (autorização no SPI). Distinto de assinaturas com boleto/cartão.

Base URL

https://api.goatpay.com.br/v1/pix-automatic

Permissões: pix-automatic/authorizations/* e pix-automatic/payment-instructions/* na API key.

Fluxo típico

Cadastre o pagador em POST /customers/create.
POST /pix-automatic/authorizations/create — gera QR com 1ª parcela + consentimento (jornada 3).
Pagador escaneia e autoriza no app do banco.
Consulte autorizações com GET .../authorizations/list ou get/{id}.
Instruções de pagamento geradas aparecem em payment-instructions/*.
Cancele com DELETE .../authorizations/cancel/{id} se necessário.

Autorizações

Método	Rota	Documentação
POST	`/authorizations/create`	Criar
GET	`/authorizations/list`	Listar
GET	`/authorizations/get/:id`	Consultar
DELETE	`/authorizations/cancel/:id`	Cancelar

Campos principais em create:

Campo	Descrição
`frequency`	`WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`
`contractId`	Identificador do contrato (máx. 35 caracteres)
`startDate`	Início da vigência `YYYY-MM-DD`
`customerId`	ID do cliente (`POST /customers/create`)
`value`	Valor recorrente em reais
`immediateQrCode`	QR da 1ª cobrança + adesão (opcional na jornada)

Instruções de pagamento

Método	Rota	Documentação
GET	`/payment-instructions/list`	Listar
GET	`/payment-instructions/get/:id`	Consultar

O produto precisa estar habilitado na sua conta. Se receber erro de produto indisponível, contate o suporte GoatPay.

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.

Programações

Agendar ou repetir envios.

Listar MEDs

Disputas da conta.

PIX automático

Autorização recorrente com consentimento.

​Status (data.status)

​coverFee (como informar o valor)

​emitFiscalInvoice (nota fiscal no depósito)

​expirationSeconds (validade do QR Code)

​Receber PIX

​Reembolsar depósito

​Enviar PIX

​Split na cobrança (opcional)

​Listagens

​Transferências programadas

​Tipos de disparo (triggerType)

​Payload da transferência

​Recorrência (recurrenceRule)

​Fluxo recomendado

​Campos na resposta (data)

​Disputas MED

​Fluxo típico

​Status da disputa

​Saldo e trilho

​Enviar evidências

​Filtros em GET /meds/list

​PIX automático

​Base URL

​Fluxo típico

​Autorizações

​Instruções de pagamento

​Endpoints

Criar cobrança

Consultar cobrança

Listar cobranças

Reembolso

Enviar PIX

Consultar envio

Listar envios

Programações

Listar MEDs

PIX automático

Status (`data.status`)

`coverFee` (como informar o valor)

`emitFiscalInvoice` (nota fiscal no depósito)

`expirationSeconds` (validade do QR Code)

Receber PIX

Reembolsar depósito

Enviar PIX

Split na cobrança (opcional)

Listagens

Transferências programadas

Tipos de disparo (`triggerType`)

Payload da transferência

Recorrência (`recurrenceRule`)

Fluxo recomendado

Campos na resposta (`data`)

Disputas MED

Fluxo típico

Status da disputa

Saldo e trilho

Enviar evidências

Filtros em `GET /meds/list`

PIX automático

Base URL

Fluxo típico

Autorizações

Instruções de pagamento

Endpoints