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.

​

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 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.
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

KEY

POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "KEY",
  "key": "[e-mail]"
}

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:

→ 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

​

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.

​

Solicitud

Pasa el id de la respuesta de iniciación como initiationId, junto con el amount a transferir:

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

→ 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.

Referencia de API: Procesar una Transferencia Pix

​

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.

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 · Recuperar una transferencia

​

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.

​

Próximos pasos

---

• Transferencias intra-PSP — Liquidación P2P interna
• Códigos QR — Generación y decodificación de códigos QR
• Operaciones de reembolso — Reembolsos y unblock
• Webhooks — Manejo de eventos de cash-out y cash-in
• Referencia de API — Detalles completos de solicitud/respuesta, headers y esquemas de campos