Conta merchant
Cada integrador possui uma conta com status (PENDING, ACTIVE, SUSPENDED, CLOSED), saldo em BRL e usuários vinculados. Operações financeiras geram transações no extrato com tipo, direção (CREDIT / DEBIT), status e metadados públicos enxutos.
Trilho PIX: PADRAO
O trilho PADRAO é o único trilho operacional da API pública. Cobre conta verificada (CPF ou CNPJ), PIX regulado, reembolso, MED no SPI, cobranças, assinaturas e loja completa (PIX e cripto). O trilho ativo na API pública é definido na chave de API ao criá-la. Não enviepixRail no body das rotas /v1/*.
Saldo: disponível, pendente e bloqueado
| Campo | Significado |
|---|---|
availableAmount | Total disponível |
pendingAmount | Reservado (saques em processamento, etc.) |
padrao | Saldo detalhado em GET /account/balance |
blockedAmount | Bloqueio administrativo ou disputa MED |
Verificação (KYC)
Contas passam por verificação (PENDING, SUBMITTED, APPROVED, REJECTED). Recursos do trilho PADRAO exigem verificação aprovada.
Nomes que confundem
| Termo | Rota | O que é |
|---|---|---|
| Receber PIX | POST /payment-pix/create | QR Code dinâmico |
| Enviar PIX | POST /transfer-pix/create | Saque para chave ou BR Code |
| Reembolso | POST /refunds/create | Devolução de depósito recebido |
| Transferência interna | POST /transfer-internal/create | Entre contas GoatPay por e-mail |
| Link de pagamento | POST /payment-links/create | Checkout hospedado (PIX e cripto) |
Cobranças e assinaturas: boleto, cartão e PIX comercial na Conta Padrão — veja Cobranças e assinaturas.
Subcontas merchant
Subcontas são carteiras lógicas sob a conta principal. Habilitação exige solicitação em Contas → Subcontas no app. PIX e saques usamsubaccountId nas rotas normais de pagamento.
Guia de subcontas
Envelope e referências
Toda resposta v1 segue:| Campo | Uso |
|---|---|
externalReference | ID do seu sistema na cobrança ou transferência |
referenceId | ID da operação no processador (público) |
requestId | Envie ao suporte em caso de erro |
Webhooks
Eventos de negócio chegam por POST HTTPS com assinatura HMAC (whsec_...). Tutorial: Webhooks na prática.