Transferencias y cash-out

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.

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

POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "KEY",
  "key": "john.doe@example.com"
}

POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "QR_CODE",
  "emv": "00020126...5802BR5913Fulano..."
}

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:

→ 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

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.

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

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

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

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.

Próximos pasos

Transferencias intra-PSP: Liquidación P2P interna
Códigos QR: Generar y decodificar códigos QR
Operaciones de devolución: Devoluciones y desbloqueo
Webhooks: Manejo de eventos de cash-out y cash-in
Referencia de API: Detalles completos de solicitud/respuesta, headers y esquemas de campos

​Por qué dos pasos

​Paso 1: Iniciar (confirmar el destino)

​Solicitud: elige la pestaña de tu tipo de iniciación

​Respuesta

​Paso 2: Procesar (mover el dinero)

​Solicitud

​El header X-Purpose

​Respuesta

​Seguimiento de una transferencia

​Cómo llegan las transferencias a Midaz

​Cuando una transferencia se atasca

​Próximos pasos

Por qué dos pasos

Paso 1: Iniciar (confirmar el destino)

Solicitud: elige la pestaña de tu tipo de iniciación

Respuesta

Paso 2: Procesar (mover el dinero)

Solicitud

El header `X-Purpose`

Respuesta

Seguimiento de una transferencia

Cómo llegan las transferencias a Midaz

Cuando una transferencia se atasca

Próximos pasos