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

# Conceitos fundamentais

> Conta, trilhos PIX, saldo, verificação, subcontas e envelope da API

Entenda os termos que aparecem em toda a documentação antes de integrar.

## 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** envie `pixRail` 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    |

Regra de saque: novas transferências PIX só são aceitas se o disponível cobrir o valor **mais** operações pendentes.

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

Mapa completo: [Rotas da API](/api-reference/escopo-api-publica).

<Note>
  **Cobranças e assinaturas:** boleto, cartão e PIX comercial na Conta Padrão — veja [Cobranças e assinaturas](/api-reference/guides/cobrancas-assinaturas).
</Note>

## 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 usam `subaccountId` nas rotas normais de pagamento.

[Guia de subcontas](/api-reference/guides/subcontas)

## Envelope e referências

Toda resposta v1 segue:

```json theme={null}
{ "success": true, "message": "OK", "data": { }, "requestId": "req_..." }
```

| 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](/pages/guides/webhooks-pratica).

## Glossário

Termos adicionais: [Glossário](/pages/glossario).