Cash Out

Withdrawals allow a user to transfer available funds from their brokerage account to a previously registered bank account. The process is initiated with a single endpoint and its status is updated asynchronously via webhook.

Prerequisites

Two conditions must be met before initiating a withdrawal:

1. Available liquid balance

The user must have liquid funds in their brokerage account. Balances held in mutual funds, open market positions, or funds pending settlement are not available for withdrawal until they are redeemed or settled.

2. Registered same-name bank account

Withdrawals can only be made to a bank account previously registered via POST /bank-accounts, whose ownership (tax ID) matches that of the brokerage account. Withdrawals to third-party accounts are not permitted.

Endpoint

POST /api/receipts/withdraw-requests/

Required headers

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

Example body

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

Field descriptions

Initial response

{
  "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": "withdrawal-user-2025-001",
  "created_at": "2025-06-10T10:30:00"
}

API Broker performs preliminary validations (available balance, same-name account, unblocked tax ID) and responds with the request in IN_PROGRESS status. This response does not confirm the withdrawal was successful. Confirmation arrives via webhook.

Request statuses

Webhook: withdraw_request_update

Every status change on the request triggers a POST notification to the webhook URL configured for your platform.

Topic

withdrawrequestupdate

Example payload — 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": "withdrawal-user-2025-001",
      "status_id": "COMPLETED",
      "status_message": "",
      "created_at": "2025-06-10T10:30:00",
      "updated_at": "2025-06-10T10:30:52Z"
    }
  ]
}

Example payload — 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": "withdrawal-user-2025-002",
      "status_id": "REJECTED",
      "status_message": "Insufficient balance",
      "created_at": "2025-06-10T11:00:00",
      "updated_at": "2025-06-10T11:00:03Z"
    }
  ]
}

Field descriptions

You may receive multiple webhooks for the same withdrawal if it goes through several statuses. Always process the most recent status_id based on updated_at. Use withdraw_request_id as the deduplication key.

Status query via GET

In addition to the webhook, you can query the status of a request at any time:

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

Useful for displaying the status in the user UI or for reconciling requests in the absence of webhooks.

Module compatibility

The balance must be liquid before initiating a withdrawal. Depending on the source of the balance:

Managing destination bank accounts

Bank accounts must be registered in advance. You can manage them with:

Only the alias of a registered account can be modified. To change the CBU, the current account must be removed and a new one registered.

Operational considerations

• SAME NAME is non-negotiable: the tax ID of the destination bank account holder must match the tax ID of the brokerage account holder. API Broker validates this automatically and rejects withdrawals to third-party accounts.
• external_id is key for idempotency: always send a unique value per request to prevent duplicate withdrawals on retries.
• The POST response is not the final confirmation: always wait for the webhook or query the status via GET before informing the user that the withdrawal was successful.
• On a REJECTED status, read the status_message field to communicate the reason to the user (insufficient balance, invalid account, blocked tax ID, etc.).
• Processing hours: automatic transfers may resolve within seconds during business banking hours. Outside those hours, requests may remain in manual validation until the start of the next business day.
• Process the webhook idempotently: the same event may be received more than once. Use withdraw_request_id as the deduplication key.

Key points to remember

1. The process is asynchronous: the POST initiates the request; the webhook confirms the outcome.
2. SAME NAME is mandatory: the bank account and brokerage account must share the same tax ID holder.
3. Always use external_id for idempotency and reconciliation on the partner's side.
4. Implementing withdraw_request_update is the only reliable way to confirm the final status.
5. withdraw_request_id is the identifier to escalate cases to support.
6. Verify balance availability before initiating the withdrawal to avoid rejections.