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

# Guia de integração PIX

> Receber PIX, enviar PIX, reembolsar depósitos, transferências programadas, PIX automático e disputas MED pela API pública.

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   |

<Note>
  `/payouts/*` é alias de `/transfer-pix/*` (permissões `payouts/*`).
</Note>

## 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](/api-reference/endpoint/payment-pix/create) e [criar transferência](/api-reference/endpoint/transfer-pix/create).

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

<Steps>
  <Step title="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](/api-reference/endpoint/payment-pix/create)
  </Step>

  <Step title="Exibir QR">
    Mostre `copyPaste`, `qrCodeBase64` ou `qrcodeUrl` no checkout. Use `expiresAt` para exibir contagem regressiva.
  </Step>

  <Step title="Acompanhar">
    `GET /payment-pix/get/{id}` ou `GET /payment-pix/list`. Webhooks: `payment.created`, `payment.paid`.

    [Consultar](/api-reference/endpoint/payment-pix/get) · [Listar](/api-reference/endpoint/payment-pix/list)
  </Step>
</Steps>

<Note>
  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](/api-reference/guides/subcontas).
</Note>

## Reembolsar depósito

Somente depósitos `COMPLETED` com `endToEndId`, no trilho **PADRÃO** da chave.

<Steps>
  <Step title="Solicitar">
    `POST /refunds/create` — `transactionId` ou `e2eId`; opcional `refundId`, `nature`, `description`. Estorno integral.

    [Solicitar reembolso](/api-reference/endpoint/refunds/create)
  </Step>

  <Step title="Acompanhar">
    `GET /refunds/get/{id}` ou `GET /refunds/list`. Webhooks: `refund.requested`, `refund.completed`, `refund.failed`.

    [Consultar](/api-reference/endpoint/refunds/get) · [Listar](/api-reference/endpoint/refunds/list)
  </Step>
</Steps>

<Warning>
  Reembolso exige `endToEndId` do depósito original.
</Warning>

## Enviar PIX

<Steps>
  <Step title="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.
  </Step>

  <Step title="Criar">
    `POST /transfer-pix/create` — `amount`, `description`, destino.

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

  <Step title="Acompanhar">
    `GET /transfer-pix/get/{id}` ou `GET /transfer-pix/list`. Webhooks: `transfer.created`, `transfer.completed`.

    [Consultar](/api-reference/endpoint/transfer-pix/get) · [Listar](/api-reference/endpoint/transfer-pix/list)
  </Step>
</Steps>

<Tip>
  `pixCopyPaste` (pagar QR de terceiro) exige trilho **PADRÃO** na API key.
</Tip>

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

```json theme={null}
{
  "items": [],
  "page": 1,
  "pageSize": 50,
  "total": 120,
  "pages": 3
}
```

Extrato completo: [`GET /account/transactions`](/api-reference/endpoint/account/transactions) ([guia Conta](/api-reference/guides/conta)).

<h2 id="transferencias-programadas">
  Transferências programadas
</h2>

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

<Steps>
  <Step title="1. Criar programação">
    `POST /transfer-scheduled/create` com `triggerType`, `payload` e parâmetros de agenda.

    [Criar programação](/api-reference/endpoint/transfer-scheduled/create)
  </Step>

  <Step title="2. Acompanhar">
    [Listar](/api-reference/endpoint/transfer-scheduled/list) ou [consultar](/api-reference/endpoint/transfer-scheduled/get) por `id`.
  </Step>

  <Step title="3. Gerenciar">
    [Pausar/retomar](/api-reference/endpoint/transfer-scheduled/update) · [Cancelar](/api-reference/endpoint/transfer-scheduled/cancel) · [Executar agora](/api-reference/endpoint/transfer-scheduled/run-now)
  </Step>
</Steps>

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

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

<h2 id="meds">
  Disputas MED
</h2>

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

### Fluxo típico

<Steps>
  <Step title="1. Webhook med.created">
    Quando uma disputa abre, a GoatPay envia `med.created` (configure em [Webhooks](/api-reference/guides/webhooks)).
  </Step>

  <Step title="2. Listar ou consultar">
    Use [Listar](/api-reference/endpoint/meds/list) ou [Consultar](/api-reference/endpoint/meds/get) pelo `id` ou `protocol`.
  </Step>

  <Step title="3. Enviar defesa">
    Enquanto `status` for `OPEN`, envie [Evidências](/api-reference/endpoint/meds/evidence) com justificativa e comprovantes.
  </Step>

  <Step title="4. Resultado">
    Após análise: `ACCEPTED`, `REJECTED`, `CANCELED` ou `EXPIRED`. Eventos `med.resolved` / `med.evidence_sent` via webhook.
  </Step>
</Steps>

### 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](/api-reference/guides/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](/api-reference/endpoint/meds/evidence).

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

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

<h2 id="pix-automatico">
  PIX automático
</h2>

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](/api-reference/guides/cobrancas-assinaturas#assinaturas).

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

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

### Autorizações

| Método | Rota                         | Documentação                                                            |
| ------ | ---------------------------- | ----------------------------------------------------------------------- |
| POST   | `/authorizations/create`     | [Criar](/api-reference/endpoint/pix-automatic/authorizations-create)    |
| GET    | `/authorizations/list`       | [Listar](/api-reference/endpoint/pix-automatic/authorizations-list)     |
| GET    | `/authorizations/get/:id`    | [Consultar](/api-reference/endpoint/pix-automatic/authorizations-get)   |
| DELETE | `/authorizations/cancel/:id` | [Cancelar](/api-reference/endpoint/pix-automatic/authorizations-cancel) |

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](/api-reference/endpoint/pix-automatic/payment-instructions-list)   |
| GET    | `/payment-instructions/get/:id` | [Consultar](/api-reference/endpoint/pix-automatic/payment-instructions-get) |

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

## Endpoints

<CardGroup cols={2}>
  <Card title="Criar cobrança" icon="qrcode" href="/api-reference/endpoint/payment-pix/create">
    QR para receber.
  </Card>

  <Card title="Consultar cobrança" icon="magnifying-glass" href="/api-reference/endpoint/payment-pix/get">
    Objeto completo em `data`.
  </Card>

  <Card title="Listar cobranças" icon="list" href="/api-reference/endpoint/payment-pix/list">
    Só entradas PIX.
  </Card>

  <Card title="Reembolso" icon="rotate-left" href="/api-reference/endpoint/refunds/create">
    Devolver depósito.
  </Card>

  <Card title="Enviar PIX" icon="paper-plane" href="/api-reference/endpoint/transfer-pix/create">
    Chave ou BR Code.
  </Card>

  <Card title="Consultar envio" icon="magnifying-glass" href="/api-reference/endpoint/transfer-pix/get">
    Status da transferência.
  </Card>

  <Card title="Listar envios" icon="list" href="/api-reference/endpoint/transfer-pix/list">
    Só saídas PIX.
  </Card>

  <Card title="Programações" icon="calendar-clock" href="/api-reference/endpoint/transfer-scheduled/create">
    Agendar ou repetir envios.
  </Card>

  <Card title="Listar MEDs" icon="scale-balanced" href="/api-reference/endpoint/meds/list">
    Disputas da conta.
  </Card>

  <Card title="PIX automático" icon="repeat" href="/api-reference/endpoint/pix-automatic/authorizations-create">
    Autorização recorrente com consentimento.
  </Card>
</CardGroup>