Cashier API

Cashier API handles customer-visible deposit, withdrawal request, and payment transaction history flows.

For automatic deposits, the module creates a local cashier transaction first, then routes the payment request to a loaded payment provider module. Provider modules are responsible for provider-specific payment creation, redirects, and status normalization. Manual deposits do not call a payment module: they create a request for manager review and return configured receiving instructions. Balance crediting is owned by the server-side Cashier flow.

Before creating a deposit, the client should call GetCashierMethods for the selected trading account. The response is already filtered by brand, account currency, customer country, enabled provider configs, loaded payment modules, and customer-level CRM overrides.

CustomerRecord.deposit_allowed is checked as a hard customer-level deposit gate before Cashier method eligibility. CustomerRecord.withdrawal_allowed is checked as a hard customer-level gate before a withdrawal request is accepted.

For withdrawals, first call GetCashierMethods with type=withdrawal for the selected trading account. The returned method's form_schema defines the fields to show and submit in details; select values and dependent values are plain strings. The withdrawal amount and currency are in the trading account's currency. Payout asset, network, and address belong to method-defined details; the API does not provide a conversion quote or convert the amount.

CreateCashierWithdrawal accepts manual methods only. It creates a request in manual_review and does not debit the trading account. A manager must process the request; that processing can debit the account after finance checks, but this API flow does not perform an external payout.

Manual deposits also use manual_review and do not credit the trading account when the request is created. Configure the customer form with form_schema and put public payment instructions in the config's settings_json object. The successful CreateCashierDeposit response returns those instructions in payment.instructions_json; a manager must process the request before the account is credited. Manual methods do not require a loaded payment module. Customer-supplied manual method fields are stored under details in the transaction's metadata_json snapshot; manual deposit instructions are also stored under instructions. Manager interfaces can use these values to show the submitted bank or payout details during review. When a manager processing operation is underway, status 11 (processing_ledger) indicates the account ledger operation is pending its result.

If a request with the same customer-scoped idempotency_key is submitted again, the duplicate is rejected; the original transaction is not returned as a replayed response. A client recovering from a timeout should check GetCashierTransactions, including a filter on idempotency_key, before creating a new request with a different key. Manual ledger work persists a pending operation before submission. Status 11 (processing_ledger) means the operation is unresolved; recovery inspects the existing ledger trade and never automatically resubmits an uncertain debit or credit. Cashier finalizes the transaction only after the matching finance trade result is confirmed committed in the separate trading database; a runtime-cache result alone does not finish it. Cashier and trading database writes are not one atomic transaction, so status 11 can remain while durable confirmation is pending.

Mobile terminal access

In CRM mode (mode = "crm"), the mobile terminal's dropdown menu provides Deposit and Withdrawal actions. Each action opens the corresponding Finance form; the selected tab is stored in the URL and remains selected after a page reload. These two actions do not require the separate display.cashier setting. They are hidden outside CRM mode.

The forms use the existing Cashier API and account availability checks. A disabled customer deposit or withdrawal permission still prevents the operation; making the menu action visible does not override these permissions.

Mobile withdrawal steps

On mobile, withdrawal uses a three-step form. Account and amount selects a real trading account and eligible manual method, then enters the debit amount in the account currency. Recipient details shows the selected method's configured fields and the optional comment. Review shows the account, method, amount, every configured detail field, and comment if entered. Empty optional values appear as —; boolean false and numeric 0 remain visible. The form uses the terminal's existing themed controls for account and method choices, with dependent choices following the selected parent value.

Use Back to return to the previous step; entered values stay in the form. Changing the account or method restarts the wizard and resets the amount, recipient details, and comment for the new selection. The terminal validates each step and sends the existing POST /cashier/withdrawal request only after the customer confirms the review. Desktop keeps the single-page form.

Confirmation creates a manual_review request. It does not reserve or debit the account at submission; manager processing performs any later account debit. If a network failure leaves the result uncertain, retrying the unchanged form reuses its idempotency_key. The server rejects duplicate keys rather than replaying the original response, so check GetCashierTransactions if a retry reports a duplicate.

Methods

Method	Endpoint	Description
GetCashierMethods	GET /cashier/methods	Returns payment methods available for a customer account
CreateCashierDeposit	POST /cashier/deposit	Creates a customer deposit transaction and starts provider payment or manual-review flow
CreateCashierWithdrawal	POST /cashier/withdrawal	Creates a customer withdrawal request for manual processing
GetCashierTransactions	GET /cashier/transactions	Returns customer cashier transaction history
ProcessCashierWebhook	POST /cashier/webhook/{provider}	Receives provider webhook and applies transaction lifecycle updates

Authorization

Customer-facing Cashier REST methods require SESSION_CUSTOMER. ProcessCashierWebhook is public and must be protected by provider signature validation in the payment module.

Statuses

Value	Name	Description
0	created	Transaction record was created
1	pending_payment	Waiting for customer/provider payment action
2	provider_confirmed	Provider confirmed successful payment
3	credited	Funds were credited to the trading account
4	credit_failed	Provider confirmed payment, but server crediting failed
5	failed	Payment flow failed
6	cancelled	Payment was cancelled
7	refunded	Payment was refunded
8	chargeback	Payment was charged back
9	manual_review	Manual BackOffice review is required
10	completed	Manual withdrawal processing completed
11	processing_ledger	A durable account ledger operation is pending or submitted; its result is unresolved