Retiros – Cash Out

El retiro de fondos permite que un usuario transfiera dinero disponible desde su cuenta comitente hacia una cuenta bancaria propia previamente registrada. El proceso se inicia con un único endpoint y su estado se actualiza de forma asincrónica mediante webhook.

Prerrequisitos

Antes de instruir un retiro deben cumplirse dos condiciones:

1. Saldo líquido disponible

El usuario debe tener fondos líquidos en su cuenta comitente. Saldo en FCI, posiciones de mercado abiertas o fondos en proceso de liquidación no están disponibles para retiro hasta que se rescaten o liquiden.

2. Cuenta bancaria same-name registrada

El retiro solo puede realizarse hacia una cuenta bancaria previamente registrada con POST /bank-accounts, cuya titularidad (CUIT) coincida con la de la cuenta comitente. No se admiten retiros a cuentas de terceros.

Endpoint

POST /api/receipts/withdraw-requests/

Headers requeridos

Authorization: Bearer {AccessToken}
Content-Type: application/json

Body de ejemplo

{
  "investment_account_id": 43101,
  "currency_id": "ARS",
  "amount": 25000.00,
  "bank_account_id": "ba-abc123",
  "external_id": "retiro-usuario-2025-001"
}

Descripción de campos

Response inicial

{
  "withdraw_request_id": 984479,
  "status_id": "IN_PROGRESS",
  "investment_account_id": 43101,
  "currency_id": "ARS",
  "amount": 25000.00,
  "bank_account_id": "ba-abc123",
  "external_id": "retiro-usuario-2025-001",
  "created_at": "2025-06-10T10:30:00"
}

API Broker realiza validaciones previas (saldo disponible, cuenta same-name, CUIT no bloqueado) y responde con la solicitud en estado IN_PROGRESS. Este response no confirma que el retiro fue exitoso. La confirmación llega por webhook.

Estados de la solicitud

Webhook: withdraw_request_update

Cada cambio de estado de la solicitud genera una notificación POST a la URL de webhook configurada para tu plataforma.

Topic

withdrawrequestupdate

Payload de ejemplo — COMPLETED

{
  "topic": "withdraw_request_update",
  "items": [
    {
      "withdraw_request_id": 984479,
      "investment_account_id": 43101,
      "currency_id": "ARS",
      "amount": 25000.00,
      "bank_account_id": 121535,
      "external_id": "retiro-usuario-2025-001",
      "status_id": "COMPLETED",
      "status_message": "",
      "created_at": "2025-06-10T10:30:00",
      "updated_at": "2025-06-10T10:30:52Z"
    }
  ]
}

Payload de ejemplo — REJECTED

{
  "topic": "withdraw_request_update",
  "items": [
    {
      "withdraw_request_id": 984480,
      "investment_account_id": 43101,
      "currency_id": "ARS",
      "amount": 100000.00,
      "bank_account_id": 121535,
      "external_id": "retiro-usuario-2025-002",
      "status_id": "REJECTED",
      "status_message": "Saldo insuficiente",
      "created_at": "2025-06-10T11:00:00",
      "updated_at": "2025-06-10T11:00:03Z"
    }
  ]
}

Descripción de campos

Podés recibir múltiples webhooks para el mismo retiro si atraviesa varios estados. Siempre procesá el status_id más reciente según updated_at. Usá withdraw_request_id como clave de deduplicación.

Consulta de estado por GET

Además del webhook, podés consultar el estado de una solicitud en cualquier momento:

GET /api/receipts/withdraw-requests/{withdraw_request_id}/

Útil para mostrar el estado en la UI del usuario o para reconciliar solicitudes ante ausencia de webhooks.

Compatibilidad con módulos

El saldo debe estar líquido antes de retirar. Según el origen del saldo:

Gestión de cuentas bancarias destino

Las cuentas bancarias deben registrarse previamente. Podés gestionarlas con:

Solo se puede modificar el alias de una cuenta registrada. Para cambiar el CBU, hay que anular la cuenta actual y registrar una nueva.

Consideraciones operativas

• SAME NAME es innegociable: el CUIT del titular de la cuenta bancaria destino debe coincidir con el CUIT del titular de la cuenta comitente. API Broker valida esto automáticamente y rechaza retiros a cuentas de terceros.
• El external_id es clave para idempotencia: siempre enviarlo con un valor único por solicitud para evitar retiros duplicados ante reintentos.
• El response del POST no es la confirmación final: siempre esperá el webhook o consultá el estado por GET antes de informarle al usuario que el retiro fue exitoso.
• Ante un REJECTED, leé el campo status_message para comunicar el motivo al usuario (saldo insuficiente, cuenta inválida, CUIT bloqueado, etc.).
• Horario de procesamiento: las transferencias automáticas pueden resolverse en segundos durante el horario bancario hábil. Fuera de ese horario pueden quedar en validación manual hasta el inicio del siguiente día hábil.
• Procesá el webhook de forma idempotente: es posible recibir el mismo evento más de una vez. Usá withdraw_request_id como clave de deduplicación.

Puntos clave para recordar

1. El proceso es asincrónico: el POST inicia la solicitud, el webhook confirma el resultado.
2. SAME NAME es obligatorio: cuenta bancaria y cuenta comitente deben tener el mismo titular por CUIT.
3. Siempre usar external_id para idempotencia y conciliación del lado del partner.
4. Implementar withdraw_request_update es la única forma confiable de confirmar el estado final.
5. withdraw_request_id es el identificador para escalar casos a soporte.
6. Verificar disponibilidad de saldo antes de instruir el retiro para evitar rechazos.