> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goatpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conta

> Saldo disponível no trilho PADRAO, extrato unificado, transferência interna e recarga de celular.

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](#transferencia-interna). Para recarga pré-paga de celular, veja [Recarga móvel](#recarga-movel).

## 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 |

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

<Note>
  Novas operações PIX creditam e debitam o saldo **PADRAO** da conta.
</Note>

[Consultar saldo](/api-reference/endpoint/account/balance)

## 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](/api-reference/endpoint/account/transactions)

<Tip>
  Para status em tempo real, combine o extrato com [Webhooks](/api-reference/guides/webhooks) em vez de polling frequente.
</Tip>

<h2 id="transferencia-interna">
  Transferência interna
</h2>

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

<Steps>
  <Step title="1. Criar transferência">
    `POST /transfer-internal/create` com `amount`, `recipientEmail` e opcionalmente `description` e `externalReference`.

    [Criar transferência interna](/api-reference/endpoint/transfer-internal/create)
  </Step>

  <Step title="2. Guardar o id">
    Use o `id` retornado (transação de **saída** da sua conta) para consultas e reconciliação.
  </Step>

  <Step title="3. Acompanhar">
    [Consultar](/api-reference/endpoint/transfer-internal/get) ou [Listar](/api-reference/endpoint/transfer-internal/list) com filtros.

    Prefira webhooks em vez de polling.
  </Step>
</Steps>

### 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`.

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

<h2 id="recarga-movel">
  Recarga móvel
</h2>

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

<Steps>
  <Step title="1. Consultar operadora">
    `GET /mobile-recharge/provider/{phoneNumber}` retorna operadora e pacotes disponíveis para o número (DDD + dígitos).

    [Consultar operadora](/api-reference/endpoint/mobile-recharge/provider)
  </Step>

  <Step title="2. Solicitar recarga">
    `POST /mobile-recharge/create` com `phone` e `amount` (um dos valores retornados no passo anterior).

    [Solicitar recarga](/api-reference/endpoint/mobile-recharge/create)
  </Step>

  <Step title="3. Acompanhar">
    [Consultar](/api-reference/endpoint/mobile-recharge/get) ou [listar](/api-reference/endpoint/mobile-recharge/list) por `id`.
  </Step>

  <Step title="4. Cancelar (se pendente)">
    Enquanto `canBeCancelled` for `true`, use [Cancelar](/api-reference/endpoint/mobile-recharge/cancel).
  </Step>
</Steps>

### Rotas

| Método | Rota                               | Documentação                                                  |
| ------ | ---------------------------------- | ------------------------------------------------------------- |
| GET    | `/mobile-recharge/provider/:phone` | [Operadora](/api-reference/endpoint/mobile-recharge/provider) |
| POST   | `/mobile-recharge/create`          | [Criar](/api-reference/endpoint/mobile-recharge/create)       |
| GET    | `/mobile-recharge/list`            | [Listar](/api-reference/endpoint/mobile-recharge/list)        |
| GET    | `/mobile-recharge/get/:id`         | [Consultar](/api-reference/endpoint/mobile-recharge/get)      |
| POST   | `/mobile-recharge/cancel/:id`      | [Cancelar](/api-reference/endpoint/mobile-recharge/cancel)    |

<Note>
  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.
</Note>

## Endpoints

| Ação                  | Rota                                                                               |
| --------------------- | ---------------------------------------------------------------------------------- |
| Saldo                 | [GET /account/balance](/api-reference/endpoint/account/balance)                    |
| Extrato               | [GET /account/transactions](/api-reference/endpoint/account/transactions)          |
| Transferência interna | [POST /transfer-internal/create](/api-reference/endpoint/transfer-internal/create) |
| Recarga móvel         | [POST /mobile-recharge/create](/api-reference/endpoint/mobile-recharge/create)     |

<CardGroup cols={2}>
  <Card title="Criar transferência" icon="paper-plane" href="/api-reference/endpoint/transfer-internal/create">
    Enviar para e-mail GoatPay.
  </Card>

  <Card title="Consultar" icon="magnifying-glass" href="/api-reference/endpoint/transfer-internal/get">
    Por `id` ou `externalReference`.
  </Card>

  <Card title="Listar" icon="list" href="/api-reference/endpoint/transfer-internal/list">
    Histórico interno.
  </Card>

  <Card title="Recarga de celular" icon="mobile" href="/api-reference/endpoint/mobile-recharge/create">
    Débito no saldo da conta.
  </Card>

  <Card title="Operadora" icon="tower-cell" href="/api-reference/endpoint/mobile-recharge/provider">
    Pacotes disponíveis por número.
  </Card>
</CardGroup>