Skip to main content

In-app deposit/withdrawal

In-app deposit/withdrawal enables brokers to embed their cashier functionality directly within cTrader.

Prerequisites​

Important

Before implementing In-app deposit/withdrawal, ensure completion of:

Architecture​

  1. In-app deposit/withdrawal opens a web browser within cTrader.
  2. cTrader requests a one-time token from the broker's CRM and embeds it in the cashier URL.
  3. The broker controls the cashier screen and handles payment processing.
  4. On success, the broker notifies cTrader of the balance change via POST /webserv/traders/{login}/changebalance.

Implementation flows​

There are two flows. They differ only in the authentication stage at the start; the in-app action stage that follows is identical.

Applies when the app has a stored accessToken and re-authenticates the session silently (see Automatic re-login flow).

The flow proceeds through the following stages:

  1. The user launches cTrader and the application finds the stored accessToken.
  2. The application sends an authorisation request with the accessToken; the cTrader backend validates it with the broker CRM (POST /oauth2/authorize). Optionally, the broker generates an inappToken.
  3. The cTrader backend authorises the session under the userId; the application optionally stores the inappToken.
  4. The user interacts with an in-app control (for example, a deposit button).
  5. The application requests an OT token; the cTrader backend asks the broker CRM to generate one for the userId, optionally passing the inappToken for verification (POST /oauth2/onetime/generate).
  6. The broker CRM returns the OT token, which the cTrader backend forwards to the application.
  7. The application opens the predefined cashier URL with the OT token (see Screen URL conventions and query parameters).
  8. The browser requests the user details; the broker CRM validates the OT token and returns them.
  9. The user completes the deposit form and the broker processes the payment through its payment service provider.
  10. The broker requests the account balance change; the cTrader backend applies it and returns the balanceHistoryId (POST /webserv/traders/{login}/changebalance).
  11. The broker confirms to the browser, which redirects to the success URL; the application closes the web browser.
  12. The cTrader backend sends a balance-change confirmation ('pump') to the platform.

URL examples​

https://brokerCrmUrl.com/inapp/deposit?token={otToken}
https://brokerCrmUrl.com/inapp/deposit?token={otToken}&account={accountId}
https://brokerCrmUrl.com/inapp/withdraw?token={otToken}
https://brokerCrmUrl.com/inapp/withdraw?token={otToken}&account={accountId}

Endpoints used​

Added by this module​

Via the identity option​

The flows above also rely on token endpoints owned by the chosen identity option:

In-app token validation​

inappToken is an optional token that lets the broker CRM bind in-app actions (such as deposit and withdrawal) to a verified SSO session. It is generated by the broker CRM, not by cTrader.

  • The CRM may return an inappToken in its response to the token-exchange and re-login endpoints — POST /oauth2/onetime/authorize and POST /oauth2/authorize (see Token verification and session). cTrader delivers it to the application automatically and includes it on the next OT-token request.
  • If the CRM returns an inappToken, it must verify that token when cTrader calls POST /oauth2/onetime/generate to obtain an OT token for the in-app action. If verification fails, the CRM must not issue the OT token — the user is then unable to open the deposit/withdrawal screen and cTrader returns CH_CLIENT_AUTH_FAILURE.
  • If the CRM does not return an inappToken, no additional verification is performed on POST /oauth2/onetime/generate.
ParameterReturned inVerified inRequiredData typeDescription
inappTokenPOST /oauth2/onetime/authorize, POST /oauth2/authorize (response body)POST /oauth2/onetime/generate (query parameter)NostringOptional validation token. If returned at authorisation, it is passed back as a query parameter when generating an OT token for an in-app action and must be verified before the OT token is issued.

Required screens​

Deposit screen​

  • URL: /inapp/deposit
  • Parameters: token, account (optional)

Deposit screen web example 1

Withdrawal screen​

  • URL: /inapp/withdraw
  • Parameters: token, account (optional)

Error handling​

Error codeDesignationDescription
400Bad RequestA required field is missing from the request body.
403CH_CLIENT_AUTH_FAILUREAccess denied to the broker's backend: invalid crmApiToken passed in POST /oauth2/onetime/generate or POST /oauth2/onetime/authorize. Re-authenticate the cTrader backend via POST /oauth2/crmApiToken.
403CH_INSUFFICIENT_PERMISSIONSA brokerName within brokerCrmName lacks access rights.
404Not FoundOT token, accessToken or userId was not found by the broker's backend.
410CID_TOKEN_EXPIREDAn expired OT token or accessToken was used. Generate a new OT token.
417CID_NON_EXISTED_TOKENAn invalid token was passed to the broker's backend.