> ## 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
> Cómo el Plugin Pix Indirecto (BTG) confirma un destino antes de mover el dinero y cómo se liquida un cash-out de Pix a lo largo del ciclo del pago.
Un cash-out de Pix mueve dinero de una cuenta hacia un destino externo. El **Plugin de Pix Indirecto (BTG)** lo ejecuta en dos pasos —**iniciar** y luego **procesar**—. Confirmas *hacia dónde* va el dinero antes de que los fondos salgan del libro contable.
## Por qué dos pasos
***
Dividir un cash-out en iniciar y procesar te da un punto de control entre "¿quién es el beneficiario?" y "enviar el dinero":
* **Verifica primero el destino.** Iniciar valida y resuelve la cuenta del beneficiario sin tocar los saldos. Una clave Pix incorrecta o una cuenta inválida falla aquí, antes de que se mueva cualquier dinero.
* **Muestra al pagador quién recibe el dinero.** La respuesta de iniciación devuelve el titular de la cuenta resuelto. Tu aplicación puede mostrar el nombre real y permitir al pagador confirmar primero.
* **Mueve fondos solo con confirmación.** No se debita nada hasta que proceses la transferencia. Si el pagador abandona el flujo, no hay ninguna reversión que hacer, porque nunca hubo movimiento que deshacer.
Esto refleja cómo funciona una buena experiencia de pago: buscar el destino, confirmar los detalles y luego pagar.
Ambos pasos son idempotentes: es seguro 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 corta duración que valida y resuelve al beneficiario **sin mover fondos**. Cómo encuentra el plugin el destino depende de con qué empieces:
| 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/rails/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 vía DICT. Consulta [Códigos QR](/es/rails/pix/btg/indirect-pix-qrcodes). |
| Los datos completos de la cuenta del beneficiario | `MANUAL` | Usa la agencia, cuenta, participante y documento del titular que proporcionas, sin búsqueda en DICT. |
Para `KEY` y `QR_CODE`, nunca proporcionas el destino. El plugin lo resuelve y lo devuelve en la respuesta, listo para mostrárselo al pagador para su confirmación.
### 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: se genera automáticamente cuando se omite.
### Respuesta
La respuesta devuelve el `id` de 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 caduque, o iníciala de nuevo. Esto evita que un destino confirmado quede obsoleto entre la búsqueda y el pago.
**Referencia de API:** [Iniciar una Transferencia Pix](/es/reference/midaz/plugins/indirect-pix/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 de procesamiento. Consulta [Webhooks](/es/rails/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 enviar un `description` opcional (máximo 140 caracteres) y `metadata` (atributos clave-valor personalizados).
#### El header `X-Purpose`
Usa el header opcional `X-Purpose` para declarar el motivo del cash-out. Su valor por defecto es `TRANSFER` cuando se omite:
| Valor | Cuándo usarlo |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSFER` | Un cash-out de Pix normal — el valor por defecto para pagos ordinarios. |
| `INSTANT_PAYMENT_REFUND` | Cuando el cash-out reembolsa un pago instantáneo recibido previamente, para que la red lo clasifique como un reembolso en lugar de una nueva transferencia. |
**Códigos QR de valor fijo:** la iniciación puede ser un `QR_CODE` cuyo payload EMV lleva un valor fijo. En ese caso, el `amount` que envías a procesar **debe ser igual** a ese valor codificado. Una discrepancia se rechaza antes de que se muevan los fondos.
### 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/rails/pix/btg/indirect-pix-intra-psp).
**Referencia de API:** [Procesar una Transferencia Pix](/es/reference/midaz/plugins/indirect-pix/process-a-pix-transfer)
## Seguimiento de una transferencia
***
Cada transferencia sigue un ciclo de vida predecible. Comienza en `PENDING`/`PROCESSING` mientras está en curso, y luego alcanza un estado terminal `COMPLETED`, `FAILED` o `CANCELLED`. Para verificar en qué punto está una transferencia, recupera una sola por su id. También puedes listar transferencias filtrando 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 `page`/`limit`/`sort_order`.
**Referencia de API:** [Listar transferencias](/es/reference/midaz/plugins/indirect-pix/list-pix-transfers) · [Recuperar una transferencia](/es/reference/midaz/plugins/indirect-pix/retrieve-a-pix-transfer)
## Cómo llegan las transferencias a Midaz
***
El plugin registra cada movimiento liquidado en Midaz como una transacción de ledger, con la pierna externa contra la cuenta `@external/BRL`. Midaz guarda el asiento contable y los metadatos de correlación — no los detalles bancarios completos de la transferencia. La sucursal, 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`), sellada cuando se conoce. El detalle completo de la contraparte vive en el registro de transferencia del plugin.
Los metadatos sellados 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 (salida) | `refundId`, `originalEndToEndId`, `returnIdentification`, `accountId`, `transferType: REFUND_CASHOUT`, `refundType`, `reason` |
| Devolución (entrada) | 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), así que el identificador E2E queda visible directamente en el asiento del ledger.
La correlación funciona en ambos sentidos:
* El plugin almacena los identificadores de la transacción y de las operaciones de Midaz en sus propios registros de transferencia y devolución, y los usa para confirmar, cancelar o revertir asientos en el ledger.
* La transacción de Midaz lleva claves de correlación en sus metadatos: filtra por `metadata.endToEndId` para cash-outs y cash-ins, o por `metadata.originalEndToEndId` / `metadata.returnIdentification` para devoluciones. El `code` de la transacción es la alternativa común — lleva el E2E ID en las transferencias y la identificación de devolución en las devoluciones.
Los metadatos personalizados que envías al procesar un cash-out (`metadata`) se almacenan con el registro de transferencia del plugin y los devuelve la API del propio plugin. **No** se copian a la transacción de Midaz — las claves de metadatos de Midaz de arriba son fijas, definidas por el plugin.
## Cuando una transferencia queda atascada
***
Si la llamada de liquidación a BTG expira antes de que BTG confirme, una transferencia puede quedarse en `PROCESSING` con sus fondos retenidos. El plugin ofrece una operación de **unblock**. Unblock vuelve a consultar la transferencia con BTG y la lleva al estado final correcto. Liquida la transferencia si BTG la confirma, o libera la retención si BTG nunca la recibió.
Unblock no aplica a las transferencias intra-PSP: no hay ninguna transacción de BTG que volver a consultar. Para el comportamiento completo de unblock y sus opciones, consulta [Operaciones de reembolso](/es/rails/pix/btg/indirect-pix-refund-operations).
## Próximos pasos
***
* [Transferencias intra-PSP](/es/rails/pix/btg/indirect-pix-intra-psp) — Liquidación P2P interna
* [Códigos QR](/es/rails/pix/btg/indirect-pix-qrcodes) — Generación y decodificación de códigos QR
* [Operaciones de reembolso](/es/rails/pix/btg/indirect-pix-refund-operations) — Reembolsos y unblock
* [Webhooks](/es/rails/pix/btg/indirect-pix-webhooks) — Manejo de eventos de cash-out y cash-in
* [Referencia de API](/es/reference/midaz/plugins/indirect-pix/initiate-a-pix-transfer) — Detalles completos de solicitud/respuesta, headers y esquemas de campos