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"
}