Skip to content

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