Skip to content

POST Create Cashier Withdrawal

Endpoint

POST /cashier/withdrawal

Command

CreateCashierWithdrawal

Authorization

Requires SESSION_CUSTOMER.

Description

Creates a withdrawal request using a brand-configured manual withdrawal method. The server rechecks method eligibility and amount limits, validates details against the method form_schema, and stores a snapshot of the method and submitted details. It rechecks country eligibility using customer country_of_residence, falling back to the trading account country when empty. Country allowlists are matched case-insensitively after trimming ASCII whitespace; a missing country does not match a restricted allowlist. Customer allow overrides do not bypass this check. Use the account currency for amount and currency; payout asset or network information belongs in the method-defined details. The endpoint does not quote or perform currency conversion. The transaction is created with type = 1, source = 1, and status = 9 (manual_review).

Before storing a new request, the server checks its amount against the current account margin snapshot using the same finance policy as the later account debit. This includes group credit/bonus policy, open exposure, the withdrawal margin reserve and the projected post-withdrawal margin state. Method limits alone do not establish sufficient account funds. A failed check creates no Cashier transaction.

This is an admission check, not a fund reservation. Pending manual-review requests do not reduce trading funds or subtract their amounts from later request eligibility. Account state can change before processing, so processing and the finance engine still perform their own checks before debiting.

The account is not debited by this endpoint. A manager must process the transaction with MngProcessManualCashierTransaction. Manager processing may debit the trading account after finance checks; it does not itself send an external payout. Automatic withdrawal methods are not supported by this endpoint.

Manual ledger processing first stores a durable pending operation and sets status 11 (processing_ledger) before submitting the account debit. If a processing response is lost or reports a server error after submission may have started, do not create another withdrawal with a new key. Query GET /cashier/transactions using the same idempotency_key and inspect the transaction status; duplicate keys are rejected, not replayed. Cashier applies the result only after the matching trade is confirmed committed in the separate trading database. A trade visible in memory alone does not finalize the transaction, and the Cashier and trading databases do not share one atomic transaction.

After the transaction is stored, the server publishes the cashier.withdrawal.created module event for the mailer, SMS and other modules. A rejected request publishes nothing.

The endpoint does not accept owner_manager_id. The Owner of the created transaction is the manager the customer is assigned to at that moment, and it is returned in the transaction object. Only the manual BackOffice commands let a manager choose it explicitly; see Transaction Ownership.

Request Parameters

Name Type Required Description
login int Yes Trading account login owned by the authenticated customer; must be positive
amount double Yes Withdrawal amount; must be at least 0.01 and within the selected method's limits
currency string Yes 1–8 characters and must match account currency
provider_config_id int Yes Positive id of an eligible withdrawal config returned by GET /cashier/methods?type=withdrawal
details object Yes Withdrawal details matching the selected method's form_schema
idempotency_key string No Customer-scoped key, max 128 characters, used to detect duplicate requests; a duplicate is rejected and does not replay the original response
comment string No Customer comment, max 512 characters
metadata_json string No Additional metadata JSON string

Request Example

POST /cashier/withdrawal
Authorization: <CUSTOMER_JWT>
Content-Type: application/json

{
  "login": 2000009,
  "amount": 50.0,
  "currency": "EUR",
  "provider_config_id": 12,
  "details": {
    "asset": "USDT",
    "network": "TRC20",
    "address": "TXabc1234567890",
    "memo": ""
  },
  "idempotency_key": "wd-001",
  "comment": "Crypto withdrawal"
}

Response

Returns the complete transaction object. attributed_manager_id records the customer's assigned manager, and owner_manager_id records the transaction owner. provider_config_id, provider, method, and the metadata_json snapshot identify the selected withdrawal method and submitted details.

transaction fields

Name Type Description
id int Cashier transaction id
customer_id int Customer id
login int Trading account login
type int 1 for withdrawal
provider string Selected provider code
method string Configured method marker
provider_config_id int Selected provider config id
provider_payment_id string Provider payment id; empty for this manual request
amount double Requested amount in account currency
currency string Transaction currency
account_currency string Trading account currency
converted_amount double Amount in account currency; equal to amount for this endpoint
conversion_rate double Applied conversion rate; 1.0 for this endpoint
status int Initial status: 9 (manual_review)
failure_reason string Failure reason; empty for a new request
idempotency_key string Submitted key, or empty when omitted
comment string Submitted comment, or empty when omitted
metadata_json string JSON string snapshot containing method id, method, display name, submitted details, and optional client metadata
source int 1 for manual source
approved_by int Approving manager id; 0 before approval
approved_time int Approval time as Unix timestamp in seconds; 0 before approval
processed_by int Processing manager id; 0 before processing
processed_time int Processing time as Unix timestamp in seconds; 0 before processing
reject_reason string Rejection reason; empty for a new request
created_time int Creation time as Unix timestamp in seconds
updated_time int Last update time as Unix timestamp in seconds
attributed_manager_id int Manager attributed to the customer when the request is created
owner_manager_id int Manager assigned as transaction owner
{
  "transaction": {
    "id": 481,
    "customer_id": 95,
    "login": 2000009,
    "type": 1,
    "provider": "manual",
    "method": "crypto",
    "provider_config_id": 12,
    "provider_payment_id": "",
    "amount": 50.0,
    "currency": "EUR",
    "account_currency": "EUR",
    "converted_amount": 50.0,
    "conversion_rate": 1.0,
    "status": 9,
    "failure_reason": "",
    "idempotency_key": "wd-001",
    "comment": "Crypto withdrawal",
    "metadata_json": "{\"provider_config_id\":12,\"method\":\"crypto\",\"display_name\":\"Cryptocurrency\",\"details\":{\"asset\":\"USDT\",\"network\":\"TRC20\",\"address\":\"TXabc1234567890\",\"memo\":\"\"}}",
    "source": 1,
    "approved_by": 0,
    "approved_time": 0,
    "processed_by": 0,
    "processed_time": 0,
    "reject_reason": "",
    "created_time": 1790580000,
    "updated_time": 1790580000,
    "attributed_manager_id": 0,
    "owner_manager_id": 0
  }
}

Errors

HTTP Error Description
400 INVALID_DATA Invalid request
400 CURRENCY_CONVERSION_REQUIRED Currency does not match account currency
400 INVALID_WITHDRAWAL_DETAILS details does not match form_schema
400 INVALID_METADATA metadata_json is not a JSON object
400 WITHDRAWAL_PROVIDER_NOT_SUPPORTED Selected method requires an automatic payout module, which is not implemented yet
403 PERMISSION_DENIED Invalid customer session or account ownership
403 WITHDRAWAL_NOT_ALLOWED Withdrawals are disabled for this customer
403 PAYMENT_METHOD_NOT_AVAILABLE Config is disabled or does not match brand, direction, country, currency, limits, or override rules; an unknown country does not match a restricted config
409 RET_TRADE_NO_MONEY Amount exceeds currently withdrawable funds or violates the projected margin/withdrawal reserve policy; no request is created
400 RET_INVALID_DATA Finance projection is unavailable or account/group finance inputs are invalid; no request is created

Example insufficient-funds response (HTTP 409):

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "RET_TRADE_NO_MONEY",
  "message": "Withdrawal amount exceeds the funds available under the account withdrawal policy"
}