MngCreateManualCashierWithdrawal¶
Creates a manual Cashier withdrawal transaction with provider = "manual" and
source = 1.
When process_now = 1, Cashier immediately posts OP_BALANCE_OUT through
Core::SetBalance with TR_REASON_CASHIER_WITHDRAWAL. The amount in the API is
positive; Cashier sends a negative balance amount internally. The transaction
is finalized only after the matching trade result is confirmed committed in
the separate trading database; the Cashier and trading databases do not share
one atomic transaction.
In the CRM, open Statement → Finance transactions → Create manual withdrawal.
The client or lead's Linked accounts section also provides this action; that
form fixes the customer and account and creates a pending transaction with
process_now = 0. Creation requires finance editing permission; immediate
processing additionally requires finance approval permission.
Access¶
The command accepts manager, admin, dealer, and CRM manager sessions. Effective access is resolved from the enabled staff manager record: a super admin may process without CRM finance flags; otherwise the manager needs CRM access, and an ordinary CRM manager needs the finance permissions below. A brand-scoped CRM admin bypasses the operation-specific finance flag.
| Role | Required permissions |
|---|---|
SESSION_CRM_ADMIN |
access_crm = 1; no additional finance permission flags required for a brand admin |
SESSION_CRM_MANAGER |
access_crm = 1, set_finance = 1; process_now = 1 additionally requires approve_finance = 1 |
SESSION_MANAGER, SESSION_ADMIN, SESSION_DEALER |
Super-admin managers are allowed; other callers need CRM access and the required finance permission |
The manager record must exist and be enabled. CRM managers remain constrained by customer/account scope, including brand and desk. CRM admins bypass these manual-method permission/scope checks, but not business checks: customer deposit/withdrawal gates, account availability and transaction processing rules still apply. The backend uses the resolved staff manager id for audit/processing. Checks run inside the handler, including direct Moleculer calls; they are not only router metadata.
Request Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
login |
int | Yes | Trading account login |
amount |
double | Yes | Withdrawal amount in account currency; at least 0.01 |
currency |
string | Yes | Transaction currency, 1–8 characters; must match account group currency |
customer_id |
int | No | Positive customer id. Defaults to account-linked customer, which must match the account |
method |
string | No | Manual method marker, max 64 characters |
provider_payment_id |
string | No | External/manual reference, max 128 characters |
idempotency_key |
string | No | Customer-scoped key, up to 128 characters. Reuse it for an identical retry; duplicate keys are rejected rather than replaying the original response |
comment |
string | No | Manager comment, max 512 characters |
metadata_json |
string | No | Metadata string stored as supplied; this command does not parse it as JSON |
owner_manager_id |
int | No | Nonnegative owner id: the manager the transaction counts towards in statistics. 0 or omitted falls back to the customer assigned_manager_id |
process_now |
int | No | 0 (default) to leave pending, 1 to start account debit immediately |
Response¶
Returns transaction.
The complete transaction fields are described in the
withdrawal transaction field table.
For this manager command, provider is manual, provider_config_id is 0,
method, provider_payment_id, and metadata_json come from the optional
request fields (defaults: empty string, empty string, and "{}" respectively).
With process_now = 0, status is 0 (created) and the account is not debited.
Immediate processing may return 11 (processing_ledger), 10 (completed),
or 5 (failed); processing audit fields reflect the approving manager and
the ledger result. Cashier confirms the result only after its matching trade
commit is acknowledged in the separate trading database. These statuses
describe the account debit, not an external payout; the Cashier and trading
databases do not share one atomic transaction.
Creation and processing errors¶
Creation happens before immediate processing. If process_now = 1 fails after
creation, the error response can include transaction for the existing record.
Keep its id and review it in Finance transactions instead of sending a new
creation request. Do not automatically retry the debit.
Before a balance debit is submitted, Cashier durably records status 11
(processing_ledger) and a linked pending operation. A server error after this
intent is stored may still include the transaction; it does not mean no debit
was submitted. Cashier reconciles the existing ledger trade after restart and
does not submit the same pending intent again. Use
MngGetCashierTransaction to inspect the
transaction and its balance operations.
After a timeout, the outcome is unknown. Reuse the same idempotency_key for an
identical retry and check the transaction history. A duplicate-key error does
not return the original transaction; creating another request with a new key
may create a second transaction.
Response example (process_now = 0)¶
{
"transaction": {
"id": 481,
"customer_id": 95,
"login": 2000009,
"type": 1,
"provider": "manual",
"method": "",
"provider_config_id": 0,
"provider_payment_id": "",
"amount": 50.0,
"currency": "EUR",
"account_currency": "EUR",
"converted_amount": 50.0,
"conversion_rate": 1.0,
"status": 0,
"failure_reason": "",
"idempotency_key": "",
"comment": "Manual withdrawal",
"metadata_json": "{}",
"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": 12
}
}
Errors¶
| Code | Error | Description |
|---|---|---|
400 |
CURRENCY_CONVERSION_REQUIRED |
Currency does not match account group currency |
400 |
INVALID_DATA |
Missing or invalid request field, including amount below 0.01 or overlong text |
400 |
ACCOUNT_NOT_AVAILABLE |
Account does not exist or is disabled |
400 |
GROUP_NOT_AVAILABLE |
Account group does not exist or is disabled |
403 |
RET_NOT_ENOUGH_RIGHTS |
Caller lacks required CRM finance permission or customer/account scope |
403 |
WITHDRAWAL_NOT_ALLOWED |
Withdrawals are disabled for this customer |
403 |
PERMISSION_DENIED |
Account is not linked to the specified customer |
404 |
CUSTOMER_NOT_FOUND |
Account has no linked customer or customer was not found |
409 |
RET_ERR_DUPLICATE |
Customer-scoped idempotency key was already used; original transaction is not replayed |
400 |
INVALID_MANAGER |
owner_manager_id does not name an existing, enabled manager with CRM access in the customer's brand. Message: Manager does not exist, is disabled, has no CRM access or belongs to another brand |
5xx |
RET_TECH_PROBLEM |
Durable transaction/finance state could not be written; inspect any returned transaction and linked balance operation |
Module events¶
After the transaction is stored, the server publishes the
cashier.withdrawal.created
module event with the transaction as created (status = 0). It does not depend on a
workflow rule. With process_now = 1 a successful processing can additionally publish
cashier.withdrawal.approved
through the workflow, when the withdrawal is completed. A rejected request publishes
nothing. Publication is asynchronous and is not delivery confirmation.
Transaction Owner¶
owner_manager_id names the Owner of the transaction, the manager it counts
towards in the money columns of
MngGetManagersCustomerStatsByFilter.
It is written once at creation and never changes;
MngUpdateCashierTransaction does not accept it.
A non-zero value must name a manager that exists, is enabled, has
access_crm = 1, is not the service recovery account, and belongs to the same
brand as the customer. Otherwise the command answers 400 INVALID_MANAGER.
When the field is omitted or 0, the Owner becomes the manager the customer is
assigned to, assigned_manager_id. A customer assigned to nobody yields
owner_manager_id = 0.
Candidates for the field are enabled managers with access_crm = 1 in the
customer's brand, which can be listed with
MngGetManagersByFilter. That command is
not available to CRM sessions, so a CRM interface has to obtain the list through
a BackOffice session.
The returned transaction already carries the resolved owner_manager_id,
alongside attributed_manager_id, which records the manager the customer was
assigned to when the transaction was created. See
Transaction Ownership.
Request Example¶
{
"command": "MngCreateManualCashierWithdrawal",
"extID": "1",
"data": {
"login": 2000009,
"amount": 50.0,
"currency": "EUR",
"comment": "Manual withdrawal",
"owner_manager_id": 12,
"process_now": 0
}
}