> ## 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.
# Transferencias y cash-out
> Envía cash-out Pix con el Plugin Pix Indirecto vía BTG: el flujo de dos pasos, iniciar y procesar, que confirma el destino antes de mover los fondos.
Un cash-out Pix mueve dinero de una cuenta a un destino externo. El **Plugin Pix Indirecto (BTG)** lo ejecuta en dos pasos: **iniciar** y luego **procesar**. Confirmas *a dónde* va el dinero antes de que los fondos salgan del ledger.
## Por qué dos pasos
***
Dividir un cash-out en iniciar y procesar te da un punto de control entre "¿quién es el receptor?" y "envía el dinero":
* **Verifica primero el destino.** Iniciar valida y resuelve la cuenta del receptor sin tocar saldos. Una clave Pix equivocada o una cuenta inválida falla aquí, antes de que se mueva dinero.
* **Muestra al pagador quién recibe el dinero.** La respuesta de iniciación devuelve el titular de la cuenta resuelta. Tu app puede mostrar el nombre real y dejar que el pagador confirme primero.
* **Mueve los fondos solo con la confirmación.** El plugin no debita nada hasta que procesas la transferencia. Si el pagador abandona el flujo, no hay movimiento que deshacer.
Ambos pasos son idempotentes. Puedes reintentarlos sin crear transferencias duplicadas. Consulta [Reintentos e idempotencia](/es/reference/retries-idempotency).
## Paso 1: Iniciar (confirmar el destino)
***
Iniciar una transferencia crea un registro de vida corta que valida y resuelve al receptor **sin mover fondos**. Cómo encuentra el plugin el destino depende de con qué empiezas:
| Con qué empiezas | Tipo de iniciación | Qué hace el plugin |
| ------------------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Una clave Pix (CPF, CNPJ, email, teléfono o EVP) | `KEY` | Busca la clave en [DICT](/es/interfaces/pix-btg/indirect-pix-dict) y resuelve la cuenta de destino por ti. |
| Un código QR (BR Code) | `QR_CODE` | Decodifica el código y resuelve el destino mediante DICT. Consulta [Códigos QR](/es/interfaces/pix-btg/indirect-pix-qrcodes). |
| Los datos completos de la cuenta del receptor | `MANUAL` | Usa la agencia, la cuenta, el participante y el documento del titular que proporcionas — sin consulta a DICT. |
Para `KEY` y `QR_CODE`, nunca proporcionas el destino tú mismo. El plugin lo resuelve y lo devuelve en la respuesta, listo para mostrárselo al pagador y que lo confirme.
### Solicitud: elige la pestaña de tu tipo de iniciación
```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"
}
}
}
```
Los valores de `type` de cuenta son `CACC` (corriente), `SVGS` (ahorro), `TRAN` (transaccional) y `OTHR` (otra). `endToEndId` es opcional para todos los tipos. El plugin genera uno cuando lo omites.
### Respuesta
La respuesta devuelve el `id` de la iniciación (usado como `initiationId` en el paso 2) y el `destination` resuelto:
```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"
}
```
Las iniciaciones expiran. La respuesta incluye un timestamp `expiresAt`. Procesa la transferencia antes de que venza, o inicia otra. Esto evita que un destino confirmado quede obsoleto entre la consulta y el pago.
**Referencia de API:** [Iniciar una transferencia Pix](/es/reference/interfaces/pix-btg/initiate-a-pix-transfer)
## Paso 2: Procesar (mover el dinero)
***
Procesar ejecuta el cash-out a partir de la iniciación que confirmaste. Debita la cuenta de origen y luego enruta el pago a BTG para su liquidación con BACEN.
La liquidación con la red Pix es **asíncrona**. La transferencia vuelve como `PROCESSING` mientras BTG liquida. El resultado final (completado o fallido) llega después mediante un webhook `cashout`. Diseña tu flujo para reaccionar a ese evento, no para esperar la respuesta del procesamiento. Consulta [Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks).
### Solicitud
Pasa el `id` de la respuesta de iniciación como `initiationId`, junto con el `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` es obligatorio. También puedes pasar un `description` opcional (máx. 140 caracteres) y `metadata` (atributos clave-valor personalizados).
#### El header `X-Purpose`
Usa el header `X-Purpose` opcional para declarar el motivo del cash-out. Cuando se omite, toma `TRANSFER` como valor predeterminado:
| Valor | Cuándo usarlo |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TRANSFER` | Un cash-out Pix normal — el predeterminado para los pagos corrientes. |
| `INSTANT_PAYMENT_REFUND` | Cuando el cash-out devuelve un pago instantáneo recibido antes, para que la red lo clasifique como devolución y no como una transferencia nueva. |
**Códigos QR de monto fijo:** la iniciación puede ser un `QR_CODE` cuyo payload EMV lleva un monto fijo. En ese caso, el `amount` que envías a procesar **debe ser igual** a ese monto codificado. Una discrepancia se rechaza antes de que se mueva ningún fondo.
### Respuesta
```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"
}
```
Cuando el destino pertenece a tu propia institución, el dinero nunca sale hacia BTG. Se liquida internamente como una transferencia P2P. Consulta [Transferencias intra-PSP](/es/interfaces/pix-btg/indirect-pix-intra-psp).
**Referencia de API:** [Procesar una transferencia Pix](/es/reference/interfaces/pix-btg/process-a-pix-transfer)
## Seguimiento de una transferencia
***
Cada transferencia sigue el mismo ciclo de vida. Empieza en `PENDING`/`PROCESSING` mientras está en tránsito, y luego llega a un `COMPLETED`, `FAILED` o `CANCELLED` terminal. Para ver en qué punto está una transferencia, consulta una sola por su id. También puedes listar transferencias filtradas por estado, tipo (cash-out o cash-in) o rango de fechas.
```json theme={null}
GET /v1/transfers?type=CASHOUT&status=COMPLETED&limit=10&page=1
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
```
Los filtros de listado incluyen `status`, `type` (`CASHOUT`/`CASHIN`), `end_to_end` y `modified_after`/`modified_before`, además de la paginación con `page`/`limit`/`sort_order`.
**Referencia de API:** [Listar transferencias](/es/reference/interfaces/pix-btg/list-pix-transfers) · [Consultar una transferencia](/es/reference/interfaces/pix-btg/retrieve-a-pix-transfer)
## Cómo llegan las transferencias a Midaz
***
El plugin registra cada movimiento liquidado en Midaz como una transacción del ledger, con el tramo externo contra la cuenta `@external/BRL`. Midaz guarda el asiento y los metadatos de correlación, no los datos bancarios completos de la transferencia. La agencia, el número de cuenta, el tipo de cuenta y la clave Pix de la contraparte nunca llegan a Midaz. La única excepción es la identidad del pagador en el cash-in (`sourceBank`, `sourceDocument`, `sourceName`), estampada cuando se conoce. El detalle completo de la contraparte vive en el registro de transferencia del plugin.
Los metadatos estampados en la transacción de Midaz dependen del flujo:
| Flujo | Claves de metadatos |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Cash-out | `initiationId`, `endToEndId`, `accountId`, `transferType: CASHOUT`, `paymentType`, `initiationType` |
| Cash-in | `endToEndId`, `accountId`, `transferType: CASHIN`, `paymentType`, `initiationType` — más `sourceBank`, `sourceDocument` y `sourceName` cuando se conoce al pagador |
| Devolución (saliente) | `refundId`, `originalEndToEndId`, `returnIdentification`, `accountId`, `transferType: REFUND_CASHOUT`, `refundType`, `reason` |
| Devolución (entrante) | Las mismas claves de devolución con `transferType: REFUND_CASHIN` |
El `code` de la transacción de Midaz también lleva el `endToEndId` (o el `returnIdentification` en las devoluciones), por lo que el identificador E2E se ve directamente en el asiento del ledger.
La correlación funciona en ambos sentidos:
* El plugin guarda los identificadores de transacción y de operación de Midaz en sus propios registros de transferencia y de devolución, y los usa para confirmar, cancelar o revertir asientos del ledger.
* La transacción de Midaz lleva claves de correlación en sus metadatos: filtra por `metadata.endToEndId` para los cash-outs y los cash-ins, o por `metadata.originalEndToEndId` / `metadata.returnIdentification` para las devoluciones. El `code` de la transacción es el respaldo común. Lleva el ID E2E en las transferencias y la identificación de devolución en las devoluciones.
Los `metadata` personalizados que pasas al procesar un cash-out se guardan con el registro de transferencia del plugin y los devuelve la propia API del plugin. **No** se copian a la transacción de Midaz. El plugin fija las claves de metadatos de Midaz indicadas arriba.
## Cuando una transferencia se atasca
***
Si la llamada de liquidación a BTG agota el timeout antes de que BTG confirme, una transferencia puede quedarse en `PROCESSING` con sus fondos retenidos. El plugin provee una operación de **desbloqueo**. El desbloqueo vuelve a verificar la transferencia con BTG y la lleva al estado final correcto. Liquida la transferencia si BTG confirma, o libera la retención si BTG nunca la recibió.
El desbloqueo no aplica a las transferencias intra-PSP. No hay transacción en BTG que volver a verificar. Para el comportamiento completo del desbloqueo y sus opciones, consulta [Operaciones de devolución](/es/interfaces/pix-btg/indirect-pix-refund-operations).
## Próximos pasos
***
* [Transferencias intra-PSP](/es/interfaces/pix-btg/indirect-pix-intra-psp): Liquidación P2P interna
* [Códigos QR](/es/interfaces/pix-btg/indirect-pix-qrcodes): Generar y decodificar códigos QR
* [Operaciones de devolución](/es/interfaces/pix-btg/indirect-pix-refund-operations): Devoluciones y desbloqueo
* [Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks): Manejo de eventos de cash-out y cash-in
* [Referencia de API](/es/reference/interfaces/pix-btg/initiate-a-pix-transfer): Detalles completos de solicitud/respuesta, headers y esquemas de campos