POST Create Cashier Deposit¶

Endpoint¶

POST /cashier/deposit

Command¶

CreateCashierDeposit

Authorization¶

Requires SESSION_CUSTOMER.

Description¶

Creates a deposit transaction for a customer-owned trading account and calls the configured payment provider module.

The server validates that login belongs to the authenticated customer and that the account and account group are enabled. It also rechecks Cashier payment method eligibility for the resolved brand/account currency/customer country before creating the transaction. This protects the submit endpoint even if the client did not call GetCashierMethods first.

The transaction is written to the Cashier cache first and then synchronized to bases/cashier.db through the Cashier DB queue.

If the provider returns a redirect URL, the response contains next_action = REDIRECT. Otherwise the transaction remains in pending_payment and the client should wait for provider-side completion.

Request Fields¶

Name	Type	Required	Description
`login`	int	Yes	Customer-owned trading account login
`provider`	string	Yes	Payment provider code loaded by Cashier
`amount`	double	Yes	Deposit amount, must be greater than `0`
`currency`	string	Yes	Payment currency. Currently must match the account group currency
`method`	string	No	Provider method marker, for example `card` or `bank_transfer`
`idempotency_key`	string	No	Retry key that prevents duplicate transaction creation
`success_url`	string	No	URL passed to provider for successful payment redirects
`failure_url`	string	No	URL passed to provider for failed/cancelled payment redirects
`comment`	string	No	Customer-visible or audit comment
`metadata_json`	string	No	JSON string with additional provider/client metadata

Request Example¶

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

{
  "login": 2000009,
  "provider": "stripe",
  "method": "card",
  "amount": 250.0,
  "currency": "USD",
  "idempotency_key": "0f9bb0e7-642d-4b70-b458-62e3993c7d2d",
  "success_url": "https://terminal.example.com/cashier/success",
  "failure_url": "https://terminal.example.com/cashier/failure"
}

Response Fields¶

Name	Type	Description
`transaction`	object	Created/updated Cashier transaction
`payment`	object	Provider payment creation result
`next_action`	string	`REDIRECT` or `WAIT_PROVIDER_PAYMENT`

`transaction`¶

Name	Type	Description
`id`	int	Cashier transaction id
`customer_id`	int	Customer id
`login`	int	Target trading account login
`type`	int	`0` deposit, `1` withdrawal
`provider`	string	Provider code
`method`	string	Provider method
`provider_payment_id`	string	External payment id returned by provider
`amount`	double	Original payment amount
`currency`	string	Payment currency
`account_currency`	string	Trading account currency used by Cashier
`converted_amount`	double	Amount in account currency
`conversion_rate`	double	Conversion rate used by Cashier
`status`	int	Cashier transaction status
`failure_reason`	string	Failure reason when status is failed
`idempotency_key`	string	Request retry key
`comment`	string	Comment
`metadata_json`	string	Additional metadata JSON string
`created_time`	int64	Creation timestamp
`updated_time`	int64	Last update timestamp

`payment`¶

Name	Type	Description
`provider_payment_id`	string	External payment id
`redirect_url`	string	URL where the client should redirect the customer
`instructions_json`	string	Provider-specific instructions JSON string
`raw_response_json`	string	Raw provider response JSON string
`status`	int	Normalized provider status
`failure_reason`	string	Provider failure reason

Response Example¶

{
  "transaction": {
    "id": 15,
    "customer_id": 5,
    "login": 2000009,
    "type": 0,
    "provider": "stripe",
    "method": "card",
    "provider_payment_id": "pi_123",
    "amount": 250.0,
    "currency": "USD",
    "account_currency": "USD",
    "converted_amount": 250.0,
    "conversion_rate": 1.0,
    "status": 1,
    "failure_reason": "",
    "idempotency_key": "0f9bb0e7-642d-4b70-b458-62e3993c7d2d",
    "comment": "",
    "metadata_json": "{}",
    "created_time": 1779270000,
    "updated_time": 1779270000
  },
  "payment": {
    "provider_payment_id": "pi_123",
    "redirect_url": "https://provider.example/pay/pi_123",
    "instructions_json": "{}",
    "raw_response_json": "{}",
    "status": 1,
    "failure_reason": ""
  },
  "next_action": "REDIRECT"
}

Errors¶

HTTP	Error	Description
`400`	`INVALID_DATA`	Request validation failed
`400`	`ACCOUNT_NOT_AVAILABLE`	Account does not exist or is disabled
`400`	`GROUP_NOT_AVAILABLE`	Account group does not exist or is disabled
`400`	`CURRENCY_CONVERSION_REQUIRED`	Requested currency differs from account currency and conversion is not supported yet
`403`	`PAYMENT_METHOD_NOT_AVAILABLE`	Provider/method is not eligible for this account/customer
`403`	`PERMISSION_DENIED`	Account does not belong to the customer
`404`	`CUSTOMER_NOT_FOUND`	Customer record was not found
`409`	`RET_ERR_DUPLICATE`	Duplicate `idempotency_key` for the same customer
`5xx`	`RET_ERR_NOSERVICE`	Payment provider is not loaded or unavailable