> ## 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 de Pix Indirecto (BTG) confirma un destino antes de mover el dinero, y cómo se liquida un cash-out de Pix.
Un cash-out de Pix mueve dinero de una cuenta hacia un destino externo. El **Plugin de Pix Indirecto (BTG)** lo maneja en dos pasos deliberados —**iniciar** y luego **procesar**— para que siempre confirme *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 le da un punto de control entre "¿quién es el beneficiario?" y "enviar el dinero":
* **Verificar 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.
* **Mostrar al pagador a quién le paga.** La respuesta de iniciación devuelve el titular de la cuenta resuelto, para que su aplicación muestre el nombre real y permita al pagador confirmar antes de comprometerse.
* **Mover fondos solo con confirmación.** No se debita nada hasta que procese 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. Consulte [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é empiece:
| Con qué empieza | 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/midaz/plugins/pix/indirect/indirect-pix-dict) y resuelve la cuenta de destino por usted. |
| Un código QR (BR Code) | `QR_CODE` | Decodifica el código y resuelve el destino vía DICT. Consulte [Códigos QR](/es/midaz/plugins/pix/indirect/indirect-pix-qrcodes). |
| Los datos completos de la cuenta del beneficiario | `MANUAL` | Usa la agencia, cuenta, participante y documento del titular que usted proporciona, sin búsqueda en DICT. |
Para `KEY` y `QR_CODE`, usted nunca proporciona el destino. El plugin lo resuelve y lo devuelve en la respuesta, listo para mostrárselo al pagador para su confirmación.
### Solicitud — elija la pestaña de su 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`: procese la transferencia antes de que caduque, o inicie 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 toma la iniciación que acaba de confirmar y ejecuta el cash-out: debita la cuenta de origen y 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, y el resultado final —completado o fallido— llega después mediante un webhook `cashout`. Diseñe su flujo para reaccionar a ese evento en lugar de esperar la respuesta de procesamiento. Consulte [Webhooks](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks).
### Solicitud
Pase 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 puede enviar un `description` opcional (máximo 140 caracteres) y `metadata` (atributos clave-valor personalizados).
#### El header `X-Purpose`
Use el header opcional `X-Purpose` para declarar por qué ocurre el 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:** cuando la iniciación es un `QR_CODE` cuyo payload EMV lleva un valor fijo, el `amount` que envía 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 su propia institución, el dinero nunca sale hacia BTG: se liquida internamente como una transferencia P2P. Consulte [Transferencias intra-PSP](/es/midaz/plugins/pix/indirect/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, puede recuperar una sola por su id, o 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&offset=0
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 `limit`/`offset`/`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)
## Cuando una transferencia queda atascada
***
Si la llamada de liquidación a BTG expira antes de confirmarse, una transferencia puede quedarse en `PROCESSING` con sus fondos aún retenidos. El plugin ofrece una operación de **unblock** que vuelve a consultar la transferencia con BTG y la lleva al estado final correcto: liquidándola si BTG la confirma, o liberando 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, consulte [Operaciones de reembolso](/es/midaz/plugins/pix/indirect/indirect-pix-refund-operations).
## Próximos pasos
***
* [Transferencias intra-PSP](/es/midaz/plugins/pix/indirect/indirect-pix-intra-psp) — Liquidación P2P interna
* [Códigos QR](/es/midaz/plugins/pix/indirect/indirect-pix-qrcodes) — Generación y decodificación de códigos QR
* [Operaciones de reembolso](/es/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Reembolsos y unblock
* [Webhooks](/es/midaz/plugins/pix/indirect/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