Conta

Use as rotas de conta para reconciliação e dashboards: saldo consolidado e extrato com todos os tipos de movimentação visíveis na conta (PIX, cripto, transferência interna, etc.). Permissões na API key: account/balance, account/transactions. Para enviar saldo a outra conta GoatPay, veja Transferência interna. Para recarga pré-paga de celular, veja Recarga móvel.

Saldo

GET /account/balance retorna o saldo da conta autenticada pela chave.

Campo	Significado
`availableAmount`	Total disponível
`pendingAmount`	Total pendente (aguardando liquidação)
`padrao`	Saldo detalhado — inclui `withdrawable`, `locked24h`, `nextUnlockAt` quando aplicável

{
  "currency": "BRL",
  "availableAmount": 1000,
  "pendingAmount": 0,
  "padrao": {
    "available": 1000,
    "pending": 0,
    "withdrawable": 1000,
    "locked24h": 0,
    "nextUnlockAt": null
  }
}

Novas operações PIX creditam e debitam o saldo PADRAO da conta.

Consultar saldo

Extrato

GET /account/transactions lista o ledger completo da conta — não apenas PIX-IN ou PIX-OUT.

Lista específica	O que retorna
`GET /payment-pix/list`	Só cobranças PIX_IN
`GET /transfer-pix/list`	Só saídas PIX_OUT
`GET /account/transactions`	Todos os tipos (`PIX_IN`, `PIX_OUT`, `CRYPTO_IN`, `INTERNAL_TRANSFER_OUT`, etc.)

Paginação e filtros

Parâmetro	Descrição
`page` / `pageSize`	Paginação (padrão 50, máximo 100)
`dateFrom` / `dateTo`	Período em `createdAt` (ISO 8601)
`status`	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELED`, `REVERSED`
`externalReference`	Filtro exato
`search`	Busca parcial em id, descrição, referência, `endToEndId`, `referenceId`, `pixKey`

Cada item do extrato segue o mesmo formato enxuto das rotas de PIX e cripto (referenceId em vez de IDs internos do processador; sem accountId, provider ou metadata). Resposta: items, page, pageSize, total, pages. Extrato da conta

Para status em tempo real, combine o extrato com Webhooks em vez de polling frequente.

Transferência interna

Transferência entre contas GoatPay no trilho PADRAO. Não é PIX para banco externo: o destinatário é identificado pelo e-mail cadastrado na GoatPay. Permissões: transfer-internal/create, transfer-internal/get, transfer-internal/list.

Como funciona

Item	Detalhe
Taxa	Sem taxa GoatPay na transferência interna
Destinatário	`recipientEmail` — e-mail da conta destino
Trilho	Origem e destino no trilho PADRAO
Liquidação	Imediata (`COMPLETED`) na criação
Webhook	`transfer.internal.completed` (envio) e `transfer.internal.received` (destino)

Cada operação gera duas transações no ledger: INTERNAL_TRANSFER_OUT (quem envia) e INTERNAL_TRANSFER_IN (quem recebe), ligadas por pairId na resposta.

Fluxo recomendado

1. Criar transferência

POST /transfer-internal/create com amount, recipientEmail e opcionalmente description e externalReference.Criar transferência interna

2. Guardar o id

Use o id retornado (transação de saída da sua conta) para consultas e reconciliação.

3. Acompanhar

Consultar ou Listar com filtros.Prefira webhooks em vez de polling.

Tipos na listagem

`type` na resposta	Significado
`INTERNAL_TRANSFER_OUT`	Você enviou
`INTERNAL_TRANSFER_IN`	Você recebeu

Campos extras: transferKind: "internal", recipientEmail / recipientName (envio), counterpartyName (recebimento), pairId.

Filtros em `GET /transfer-internal/list`

Mesmos parâmetros das outras listagens:

Parâmetro	Descrição
`page` / `pageSize`	Paginação (máx. 100)
`dateFrom` / `dateTo`	Período (`createdAt`, ISO 8601)
`status`	Ex.: `COMPLETED`, `PENDING`
`externalReference`	Filtro exato
`search`	id, descrição, referência, etc.

Resposta: items, page, pageSize, total, pages.

Não é possível transferir para a própria conta nem para e-mail inexistente na GoatPay. Valor mínimo R$ 1,00.

Recarga móvel

Recarga pré-paga de celular debitada do saldo da Conta Padrão. Permissões: mobile-recharge/create, list, get, cancel, provider. No dashboard: Transações → Recarga de celular.

Fluxo recomendado

1. Consultar operadora

GET /mobile-recharge/provider/{phoneNumber} retorna operadora e pacotes disponíveis para o número (DDD + dígitos).Consultar operadora

2. Solicitar recarga

POST /mobile-recharge/create com phone e amount (um dos valores retornados no passo anterior).Solicitar recarga

3. Acompanhar

Consultar ou listar por id.

4. Cancelar (se pendente)

Enquanto canBeCancelled for true, use Cancelar.

Rotas

Método	Rota	Documentação
GET	`/mobile-recharge/provider/:phone`	Operadora
POST	`/mobile-recharge/create`	Criar
GET	`/mobile-recharge/list`	Listar
GET	`/mobile-recharge/get/:id`	Consultar
POST	`/mobile-recharge/cancel/:id`	Cancelar

A operadora não é enviada no create — ela é inferida automaticamente a partir do número. Use GET /mobile-recharge/provider antes para exibir opções no checkout.

Endpoints

Ação	Rota
Saldo	GET /account/balance
Extrato	GET /account/transactions
Transferência interna	POST /transfer-internal/create
Recarga móvel	POST /mobile-recharge/create

Criar transferência

Enviar para e-mail GoatPay.

Consultar

Por id ou externalReference.

Listar

Histórico interno.

Recarga de celular

Débito no saldo da conta.

Operadora

Pacotes disponíveis por número.

Introdução

Webhooks

PIX

Loja

Subcontas

Conta

Saldo

Extrato

Paginação e filtros

Transferência interna

Como funciona

Fluxo recomendado

Tipos na listagem

Filtros em `GET /transfer-internal/list`

Recarga móvel

Fluxo recomendado

Rotas

Endpoints

Criar transferência

Consultar

Listar

Recarga de celular

Operadora

​Saldo

​Extrato

​Paginação e filtros

​Transferência interna

​Como funciona

​Fluxo recomendado

​Tipos na listagem

​Filtros em GET /transfer-internal/list

​Recarga móvel

​Fluxo recomendado

​Rotas

​Endpoints

Criar transferência

Consultar

Listar

Recarga de celular

Operadora

Saldo

Extrato

Paginação e filtros

Transferência interna

Como funciona

Fluxo recomendado

Tipos na listagem

Filtros em `GET /transfer-internal/list`

Recarga móvel

Fluxo recomendado

Rotas

Endpoints