8. Balance and withdrawals

Balance: GET /merchant/wallet (global per currency) and GET /applications/{id}/balance (per application). Details and responses: Individual merchant, step 8.

Instant withdrawal

POST/withdrawalsSession token

For a business, application_id is required. Same prior check (POST /withdrawals/account-inquiry), same bodies and responses as for individuals. History: GET /withdrawals.

  • For a bank transfer, add destination_type: "bank" and application_id. The IBAN on the business profile is used; see the individual merchant's "Withdraw by bank transfer" section for requirements, examples and errors.

Scheduled withdrawal

POST/scheduled-withdrawalsSession token

Business only: the amount is held when each occurrence is triggered.

Request body
{
  "application_id": 12,
  "amount": 15000,
  "destination_provider": "orange_money_cm",
  "destination_phone_number": "696246686",
  "frequency": "monthly",
  "day_of_month": 1,
  "time_of_day": "12:30",
  "starts_from": "2026-12-01",
  "currency": "XAF"
}
Response 201 (excerpt)
{
  "success": true,
  "data": {
    "application_id": 12,
    "amount": 15000,
    "frequency": "monthly",
    "day_of_month": 1,
    "time_of_day": "12:30:00",
    "next_execution_at": "2026-12-01T12:30:00Z",
    "is_active": true,
    "status": "active",
    "currency": "XAF"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}
  • frequency: once, daily, weekly (requires day_of_week, 1 = Monday to 7 = Sunday), monthly (requires day_of_month, 1 to 31; moved to the last day of a shorter month).
  • Statuses: active, paused, completed (finished once frequency), cancelled. Edit / pause: PATCH /scheduled-withdrawals/{id}. Cancel: DELETE /scheduled-withdrawals/{id}. Occurrence history: GET /scheduled-withdrawals/executions.
  • Errors: 403 (not a business account), 422 (invalid data).