> ## 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
> Envie cash-out Pix pelo Plugin Pix Indireto via BTG: o fluxo de dois passos, iniciar e processar, que confirma o destino antes de mover os fundos.
Um cash-out Pix move dinheiro de uma conta para um destino externo. O **Plugin Pix Indireto (BTG)** executa isso em dois passos: **iniciar** e depois **processar**. Você confirma *para onde* o dinheiro vai antes de qualquer valor sair do ledger.
## Por que dois passos
***
Dividir um cash-out em iniciar e processar dá a você um ponto de verificação entre "quem é o recebedor?" e "envie o dinheiro":
* **Confirme o destino primeiro.** A iniciação valida e resolve a conta do recebedor sem tocar em saldos. Uma chave Pix errada ou uma conta inválida falha aqui, antes de qualquer dinheiro se mover.
* **Mostre ao pagador quem recebe o dinheiro.** A resposta da iniciação retorna o titular resolvido da conta. Seu app pode mostrar o nome real e deixar o pagador confirmar antes.
* **Mova os fundos apenas na confirmação.** O plugin não debita nada até você processar a transferência. Se o pagador abandonar o fluxo, não há movimentação a desfazer.
Os dois passos são idempotentes. Você pode repeti-los sem criar transferências duplicadas. Veja [Novas tentativas e idempotência](/pt/reference/retries-idempotency).
## Passo 1: iniciar (confirme o destino)
***
Iniciar uma transferência cria um registro de vida curta que valida e resolve o recebedor **sem mover fundos**. Como o plugin encontra o destino depende do que você tem no começo:
| Você começa com | Tipo de iniciação | O que o plugin faz |
| ------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| Uma chave Pix (CPF, CNPJ, email, telefone ou EVP) | `KEY` | Consulta a chave no [DICT](/pt/interfaces/pix-btg/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 pelo DICT. Veja [QR Codes](/pt/interfaces/pix-btg/indirect-pix-qrcodes). |
| Os dados completos da conta do recebedor | `MANUAL` | Usa a agência, a conta, o participante e o documento do titular que você informa — sem consulta ao DICT. |
Para `KEY` e `QR_CODE`, você nunca informa 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` da conta são `CACC` (corrente), `SVGS` (poupança), `TRAN` (transacional) e `OTHR` (outra). `endToEndId` é opcional para todos os tipos. O plugin gera um quando você o omite.
### 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 de novo. Isso impede que um destino confirmado fique desatualizado entre a consulta e o pagamento.
**Referência da API:** [Iniciar uma transferência Pix](/pt/reference/interfaces/pix-btg/initiate-a-pix-transfer)
## Passo 2: processar (mover o dinheiro)
***
O processamento executa o cash-out a partir da iniciação que você confirmou. Ele debita a conta de origem e depois roteia o pagamento ao BTG para liquidação com o BACEN.
A liquidação com a rede Pix é **assíncrona**. A transferência volta como `PROCESSING` enquanto o BTG liquida. O resultado final (concluído ou falho) chega depois por um webhook `cashout`. Monte seu fluxo para reagir a esse evento, não para esperar a resposta do processamento. Veja [Webhooks](/pt/interfaces/pix-btg/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 passar um `description` opcional (máximo de 140 caracteres) e `metadata` (atributos chave-valor customizados).
#### O header `X-Purpose`
Use o header `X-Purpose` opcional para declarar o motivo do cash-out. Ele assume `TRANSFER` como padrão quando é omitido:
| Valor | Quando usar |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSFER` | Um cash-out Pix comum — o padrão para pagamentos ordinários. |
| `INSTANT_PAYMENT_REFUND` | Quando o cash-out devolve um pagamento instantâneo recebido antes, para que a rede possa classificá-lo como devolução e não como nova transferência. |
**QR codes de valor fixo:** a iniciação pode ser um `QR_CODE` cujo payload EMV carrega um valor fixo. Nesse caso, o `amount` que você envia ao processar **deve ser igual** ao valor codificado. Uma divergência é rejeitada antes de qualquer fundo se mover.
### 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 liquida internamente como uma transferência P2P. Veja [Transferências intra-PSP](/pt/interfaces/pix-btg/indirect-pix-intra-psp).
**Referência da API:** [Processar uma transferência Pix](/pt/reference/interfaces/pix-btg/process-a-pix-transfer)
## Acompanhar uma transferência
***
Toda transferência segue o mesmo ciclo de vida. Ela começa em `PENDING`/`PROCESSING` enquanto está em trânsito e depois chega a um `COMPLETED`, `FAILED` ou `CANCELLED` terminal. Para ver em que ponto uma transferência está, consulte uma delas pelo id. Você também pode listar transferências filtradas por status, tipo (cash-out ou cash-in) ou período.
```json theme={null}
GET /v1/transfers?type=CASHOUT&status=COMPLETED&limit=10&page=1
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 `page`/`limit`/`sort_order`.
**Referência da API:** [Listar transferências](/pt/reference/interfaces/pix-btg/list-pix-transfers) · [Consultar uma transferência](/pt/reference/interfaces/pix-btg/retrieve-a-pix-transfer)
## Como as transferências chegam ao Midaz
***
O plugin lança toda movimentação liquidada no Midaz como uma transação no ledger, com a perna externa contra a conta `@external/BRL`. O Midaz registra o lançamento e os metadados de correlação, não os dados bancários completos da transferência. Agência, número da conta, tipo de conta e chave Pix da contraparte nunca chegam ao Midaz. A única exceção é a identidade do pagador no cash-in (`sourceBank`, `sourceDocument`, `sourceName`), gravada quando é conhecida. O detalhe completo da contraparte fica no registro de transferência do plugin.
Os metadados gravados na transação do Midaz dependem do fluxo:
| Fluxo | Chaves de metadados |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cash-out | `initiationId`, `endToEndId`, `accountId`, `transferType: CASHOUT`, `paymentType`, `initiationType` |
| Cash-in | `endToEndId`, `accountId`, `transferType: CASHIN`, `paymentType`, `initiationType` — mais `sourceBank`, `sourceDocument` e `sourceName` quando o pagador é conhecido |
| Devolução (saída) | `refundId`, `originalEndToEndId`, `returnIdentification`, `accountId`, `transferType: REFUND_CASHOUT`, `refundType`, `reason` |
| Devolução (entrada) | As mesmas chaves de devolução com `transferType: REFUND_CASHIN` |
O `code` da transação no Midaz também carrega o `endToEndId` (ou a `returnIdentification` nas devoluções), então o identificador E2E fica visível direto no lançamento do ledger.
A correlação funciona nos dois sentidos:
* O plugin guarda os identificadores de transação e de operação do Midaz nos seus próprios registros de transferência e de devolução, e os usa para confirmar, cancelar ou reverter lançamentos.
* A transação do Midaz carrega chaves de correlação nos seus metadados: filtre por `metadata.endToEndId` para cash-outs e cash-ins, ou por `metadata.originalEndToEndId` / `metadata.returnIdentification` para devoluções. O `code` da transação é o fallback comum. Ele carrega o ID E2E nas transferências e a identificação de devolução nas devoluções.
O `metadata` customizado que você passa ao processar um cash-out é guardado com o registro de transferência do plugin e retornado pela API do próprio plugin. Ele **não** é copiado para a transação do Midaz. O plugin fixa as chaves de metadados do Midaz listadas acima.
## Quando uma transferência trava
***
Se a chamada de liquidação ao BTG der timeout antes de o BTG confirmar, uma transferência pode ficar em `PROCESSING` com os fundos retidos. O plugin oferece uma operação de **desbloqueio**. O desbloqueio reconsulta a transferência no BTG e a leva ao estado final correto. Ele liquida a transferência se o BTG confirmar, ou libera a retenção se o BTG nunca a tiver recebido.
O desbloqueio não se aplica a transferências intra-PSP. Não há transação no BTG para reconsultar. Para o comportamento completo do desbloqueio e suas opções, veja [Operações de devolução](/pt/interfaces/pix-btg/indirect-pix-refund-operations).
## Próximos passos
***
* [Transferências intra-PSP](/pt/interfaces/pix-btg/indirect-pix-intra-psp): Liquidação P2P interna
* [QR Codes](/pt/interfaces/pix-btg/indirect-pix-qrcodes): Geração e decodificação de QR codes
* [Operações de devolução](/pt/interfaces/pix-btg/indirect-pix-refund-operations): Devoluções e desbloqueio
* [Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks): Tratamento de eventos de cash-out e cash-in
* [Referência da API](/pt/reference/interfaces/pix-btg/initiate-a-pix-transfer): Detalhes completos de requisição e resposta, headers e schemas de campos