Saltar al contenido principal
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.

​
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é empiezaTipo de iniciaciónQué hace el plugin
Una clave Pix (CPF, CNPJ, email, teléfono o EVP)KEYBusca la clave en DICT y resuelve la cuenta de destino por usted.
Un código QR (BR Code)QR_CODEDecodifica el código y resuelve el destino vía DICT. Consulte Códigos QR.
Los datos completos de la cuenta del beneficiarioMANUALUsa 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

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

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

​
Solicitud

Pase 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 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:
ValorCuándo usarlo
TRANSFERUn cash-out de Pix normal — el valor por defecto para pagos ordinarios.
INSTANT_PAYMENT_REFUNDCuando 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

→ 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.
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, puede recuperar una sola por su id, o listar transferencias filtrando por estado, tipo (cash-out o cash-in) o rango de fechas. 
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 · Recuperar una transferencia

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

​
Próximos pasos