> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Transferências e cash-out
> Como o Plugin de Pix Indireto (BTG) confirma um destino antes de mover o dinheiro, e como um cash-out de Pix é liquidado.
Um cash-out de Pix move dinheiro de uma conta para um destino externo. O **Plugin de Pix Indireto (BTG)** faz isso em dois passos deliberados —**iniciar** e depois **processar**— para que você sempre confirme *para onde* o dinheiro está indo antes de qualquer valor sair do ledger.
## Por que dois passos
***
Dividir um cash-out em iniciar e processar cria um ponto de verificação entre "quem é o beneficiário?" e "enviar o dinheiro":
* **Verifique o destino primeiro.** Iniciar valida e resolve a conta do beneficiário sem tocar nos saldos. Uma chave Pix incorreta ou uma conta inválida falha aqui — antes de qualquer dinheiro se mover.
* **Mostre ao pagador para quem ele está pagando.** A resposta de iniciação retorna o titular da conta resolvido, para que seu aplicativo exiba o nome real e permita ao pagador confirmar antes de se comprometer.
* **Mova fundos apenas com confirmação.** Nada é debitado até você processar a transferência. Se o pagador abandonar o fluxo, não há nenhuma reversão a fazer — nunca houve movimentação a desfazer.
Isso reflete como uma boa experiência de pagamento funciona: buscar o destino, confirmar os detalhes e então pagar.
Ambos os passos são idempotentes — é seguro repeti-los sem criar transferências duplicadas. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency).
## Passo 1 — Iniciar: confirmar o destino
***
Iniciar uma transferência cria um registro de curta duração que valida e resolve o beneficiário **sem mover fundos**. Como o plugin encontra o destino depende do que você tem em mãos:
| Com o que você começa | Tipo de iniciação | O que o plugin faz |
| ------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Uma chave Pix (CPF, CNPJ, email, telefone ou EVP) | `KEY` | Busca a chave no [DICT](/pt/midaz/plugins/pix/indirect/indirect-pix-dict) e resolve a conta de destino para você. |
| Um QR code (BR Code) | `QR_CODE` | Decodifica o código e resolve o destino via DICT. Consulte [QR Codes](/pt/midaz/plugins/pix/indirect/indirect-pix-qrcodes). |
| Os dados completos da conta do beneficiário | `MANUAL` | Usa a agência, conta, participante e documento do titular que você fornece — sem consulta ao DICT. |
Para `KEY` e `QR_CODE`, você nunca fornece o destino. O plugin o resolve e o retorna na resposta, pronto para mostrar ao pagador para confirmação.
### Requisição — escolha a aba do seu tipo de iniciação
```json KEY theme={null}
POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
"initiationType": "KEY",
"key": "john.doe@example.com"
}
```
```json QR_CODE theme={null}
POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
"initiationType": "QR_CODE",
"emv": "00020126...5802BR5913Fulano..."
}
```
```json MANUAL theme={null}
POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
"initiationType": "MANUAL",
"destination": {
"account": {
"branch": "0001",
"number": "123456789",
"participant": "12345678",
"type": "CACC"
},
"owner": {
"document": "12345678901",
"name": "John Doe"
}
}
}
```
Os valores de `type` de conta são `CACC` (corrente), `SVGS` (poupança), `TRAN` (transacional) e `OTHR` (outra). `endToEndId` é opcional para todos os tipos — é gerado automaticamente quando omitido.
### Resposta
A resposta retorna o `id` da iniciação (usado como `initiationId` no passo 2) e o `destination` resolvido:
```json theme={null}
→ 201 Created
{
"id": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
"initiationType": "KEY",
"endToEndId": "E1234567820240101000001234567890",
"destination": { "account": { ... }, "owner": { ... } },
"expiresAt": "2024-01-15T11:00:00Z",
"createdAt": "2024-01-15T10:30:00Z"
}
```
As iniciações expiram. A resposta inclui um timestamp `expiresAt` — processe a transferência antes que ela expire, ou inicie novamente. Isso evita que um destino confirmado fique obsoleto entre a busca e o pagamento.
**Referência da API:** [Iniciar uma Transferência Pix](/pt/reference/midaz/plugins/indirect-pix/initiate-a-pix-transfer)
## Passo 2 — Processar: mover o dinheiro
***
Processar pega a iniciação que você acabou de confirmar e executa o cash-out: debita a conta de origem e roteia o pagamento para o BTG para liquidação com o BACEN.
A liquidação com a rede Pix é **assíncrona**. A transferência retorna como `PROCESSING` enquanto o BTG liquida, e o resultado final — concluído ou falho — chega depois por um webhook `cashout`. Construa seu fluxo para reagir a esse evento em vez de esperar pela resposta de processamento. Consulte [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks).
### Requisição
Passe o `id` da resposta de iniciação como `initiationId`, junto com o `amount` a transferir:
```json theme={null}
POST /v1/transfers/cashout/process
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
X-Purpose: TRANSFER
{
"initiationId": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
"amount": "100.50"
}
```
`amount` é obrigatório. Você também pode enviar um `description` opcional (máximo 140 caracteres) e `metadata` (atributos chave-valor personalizados).
#### O header `X-Purpose`
Use o header opcional `X-Purpose` para declarar por que o cash-out está acontecendo. O valor padrão é `TRANSFER` quando omitido:
| Valor | Quando usar |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSFER` | Um cash-out de Pix comum — o padrão para pagamentos ordinários. |
| `INSTANT_PAYMENT_REFUND` | Quando o cash-out está devolvendo um pagamento instantâneo recebido anteriormente, para que a rede o classifique como uma devolução em vez de uma nova transferência. |
**QR codes de valor fixo:** quando a iniciação é um `QR_CODE` cujo payload EMV carrega um valor fixo, o `amount` que você envia para processar **deve ser igual** a esse valor codificado. Uma divergência é rejeitada antes de qualquer movimentação de fundos.
### Resposta
```json theme={null}
→ 201 Created
{
"id": "019c96a0-0c21-71f9-a487-66a1258278a1",
"endToEndId": "E1234567820240101000001234567890",
"amount": "100.50",
"status": "PROCESSING",
"type": "CASHOUT",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
```
Quando o destino pertence à sua própria instituição, o dinheiro nunca sai para o BTG — ele é liquidado internamente como uma transferência P2P. Consulte [Transferências intra-PSP](/pt/midaz/plugins/pix/indirect/indirect-pix-intra-psp).
**Referência da API:** [Processar uma Transferência Pix](/pt/reference/midaz/plugins/indirect-pix/process-a-pix-transfer)
## Acompanhando uma transferência
***
Toda transferência segue um ciclo de vida previsível: começa em `PENDING`/`PROCESSING` enquanto está em andamento, e depois alcança um status terminal `COMPLETED`, `FAILED` ou `CANCELLED`. Para verificar em que ponto uma transferência está, você pode recuperar uma única pelo id, ou listar transferências filtrando por status, tipo (cash-out ou cash-in) ou intervalo de datas.
```json theme={null}
GET /v1/transfers?type=CASHOUT&status=COMPLETED&limit=10&offset=0
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
```
Os filtros de listagem incluem `status`, `type` (`CASHOUT`/`CASHIN`), `end_to_end` e `modified_after`/`modified_before`, além da paginação `limit`/`offset`/`sort_order`.
**Referência da API:** [Listar transferências](/pt/reference/midaz/plugins/indirect-pix/list-pix-transfers) · [Recuperar uma transferência](/pt/reference/midaz/plugins/indirect-pix/retrieve-a-pix-transfer)
## Quando uma transferência fica travada
***
Se a chamada de liquidação ao BTG expirar antes de confirmar, uma transferência pode ficar em `PROCESSING` com seus fundos ainda retidos. O plugin oferece uma operação de **unblock** que reconsulta a transferência com o BTG e a leva ao status final correto — liquidando-a se o BTG confirmar, ou liberando a retenção se o BTG nunca a recebeu.
Unblock não se aplica a transferências intra-PSP — não há nenhuma transação do BTG para reconsultar. Para o comportamento completo do unblock e suas opções, consulte [Operações de devolução](/pt/midaz/plugins/pix/indirect/indirect-pix-refund-operations).
## Próximos passos
***
* [Transferências intra-PSP](/pt/midaz/plugins/pix/indirect/indirect-pix-intra-psp) — Liquidação P2P interna
* [QR Codes](/pt/midaz/plugins/pix/indirect/indirect-pix-qrcodes) — Geração e decodificação de QR codes
* [Operações de devolução](/pt/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Devoluções e unblock
* [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Tratamento de eventos de cash-out e cash-in
* [Referência da API](/pt/reference/midaz/plugins/indirect-pix/initiate-a-pix-transfer) — Detalhes completos de requisição/resposta, headers e schemas de campos