# 7. Withdrawals

There are two ways to withdraw money from a customer's account, depending on whether the cash is already available.

## Cash withdrawal

If the account has sufficient cash balance, use the withdrawal endpoint to pay out directly to the customer's validated bank account.
A `bankAccount` may be connected through the `addBankAccount` [journey](/guides/api-guide/getting-started/autogiro-payments) or during allocation plan or savingsplan setup. Money arrives within 1-2 business days.

### Withdrawal request schema

```json
{
  "$ref": "#/components/schemas/withdrawal_request",
  "components": {
    "schemas": {
      "uuid": {
        "$id": "/models/uuid.yaml",
        "title": "UUID",
        "type": "string",
        "example": "49ad7378-121c-4a53-9894-dfd14a7b4877",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      },
      "fee_types": {
        "$id": "/models/transaction/fee_types.yaml",
        "title": "feeType",
        "type": "string",
        "description": "- `client_fee_oneoff` — One-off fee\n- `client_fee_ongoing` — Ongoing fee\n- `client_fee_transaction` — Transactional fee\n- `client_fee_performance` — Performance fee\n- `client_fee_other` — Other fee\n",
        "enum": [
          "client_fee_oneoff",
          "client_fee_ongoing",
          "client_fee_transaction",
          "client_fee_performance",
          "client_fee_other"
        ]
      },
      "client_ref": {
        "$id": "/models/common/client_ref.yaml",
        "type": "string",
        "title": "client reference",
        "description": "Client applied ref",
        "example": "my_order_123"
      },
      "executor_ref": {
        "$id": "/models/common/executor_ref.yaml",
        "type": "string",
        "title": "executor reference",
        "description": "SSN of the individual executing the operation. On write operations, validated against the account owner's SSN — requests with a mismatched value are rejected.\n\nThe partner is responsible for verifying the executor's identity (e.g. via BankID) before including this value.\n",
        "example": "197001010003"
      },
      "withdrawal_request": {
        "$id": "/models/transaction/withdrawal_request.yaml",
        "type": "object",
        "title": "withdrawal",
        "description": "Withdrawal",
        "required": [
          "amount",
          "executorRef",
          "withdrawalType"
        ],
        "properties": {
          "clientRef": {
            "$ref": "#/components/schemas/client_ref"
          },
          "executorRef": {
            "$ref": "#/components/schemas/executor_ref"
          },
          "amount": {
            "type": "number",
            "description": "Transaction amount"
          }
        },
        "oneOf": [
          {
            "type": "object",
            "title": "bank_payout",
            "description": "Payout to customers bank account",
            "required": [
              "bankAccount"
            ],
            "properties": {
              "withdrawalType": {
                "type": "string",
                "const": "bank_payout",
                "title": "bank_payout",
                "description": "Payout to customers bank account"
              },
              "bankAccount": {
                "$ref": "#/components/schemas/uuid",
                "description": "ID of bank account from `account` schema"
              }
            }
          },
          {
            "type": "object",
            "title": "fee_charge",
            "description": "Charge of fee to customers account",
            "required": [
              "feeType"
            ],
            "properties": {
              "withdrawalType": {
                "type": "string",
                "const": "fee_charge",
                "title": "fee_charge",
                "description": "Charge of fee to customers account"
              },
              "feeType": {
                "$ref": "#/components/schemas/fee_types"
              }
            }
          }
        ]
      }
    }
  }
}
```

## Order withdrawal (sell and pay out)

When the customer wants to sell fund units **and** withdraw the proceeds in one step, use the order withdrawal endpoint. This combines what would otherwise be two separate calls (redeem + withdraw) into one. Once the redemption settles, a bank payout is automatically triggered.

Like regular orders, you can dry-run with `?validate-only`.

### Order withdrawal request schema

```json
{
  "$ref": "#/components/schemas/withdrawal",
  "components": {
    "schemas": {
      "uuid": {
        "$id": "/models/uuid.yaml",
        "title": "UUID",
        "type": "string",
        "example": "49ad7378-121c-4a53-9894-dfd14a7b4877",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
      },
      "executor_ref": {
        "$id": "/models/common/executor_ref.yaml",
        "type": "string",
        "title": "executor reference",
        "description": "SSN of the individual executing the operation. On write operations, validated against the account owner's SSN — requests with a mismatched value are rejected.\n\nThe partner is responsible for verifying the executor's identity (e.g. via BankID) before including this value.\n",
        "example": "197001010003"
      },
      "withdrawal": {
        "$id": "/models/order/order_redemption_withdrawal.yaml",
        "type": "object",
        "description": "redemption order with withdrawal",
        "title": "redemption order for withdrawal",
        "required": [
          "account",
          "instrument",
          "units",
          "executorRef"
        ],
        "properties": {
          "orderType": {
            "type": "string",
            "enum": [
              "redemption"
            ]
          },
          "account": {
            "$ref": "#/components/schemas/uuid",
            "description": "Account ID"
          },
          "clientRef": {
            "type": "string",
            "description": "Client applied ref",
            "example": "my_order_123"
          },
          "executorRef": {
            "$ref": "#/components/schemas/executor_ref"
          },
          "instrument": {
            "type": "string",
            "example": "US64110L1061USD",
            "description": "Fondo instrument ID"
          },
          "units": {
            "type": "number",
            "example": 1000,
            "description": "Number of units. 7 decimals"
          },
          "paymentAccount": {
            "$ref": "#/components/schemas/uuid",
            "description": "Payment account ID to create bank payout for. **Deprecated: Use bankAccount instead.**",
            "deprecated": true
          },
          "bankAccount": {
            "$ref": "#/components/schemas/uuid",
            "description": "Bank account ID to create bank payout for. Required."
          }
        }
      }
    }
  }
}
```

## Next steps

- **Real-time updates** — connect a [WebSocket subscription](/guides/api-guide/subscriptions) to receive live events for orders, transactions, and journeys instead of polling.
- **API Reference** — see the full [API Reference](/openapi/api/section/overview) for all available endpoints and schemas.
- **API Fundamentals** — read about [General API setup](/guides/api-guide/api-fundamentals) for details on sandbox, NPC, and production.