In-App Deposit/Withdrawal

InApp Deposit/Withdraw enables brokers to embed their cashier functionality directly within cTrader, allowing users to perform financial transactions without leaving the trading platform. This module provides a seamless funding experience while maintaining broker control over payment processing.

Overview

The InApp Deposit/Withdraw module enables:

• Embedded cashier functionality within cTrader interface
• Seamless deposit and withdrawal workflows
• Broker-branded payment processing screens
• Real-time balance updates and confirmations
• Support for multiple payment methods and currencies

Prerequisites

Before implementing InApp Deposit/Withdraw, ensure completion of:

• Prerequisites: All foundation requirements
• Identity options: Either SSO User creation and authorisation or One-time token handoff

Architecture

Integration Flow

1. User Initiation: User clicks deposit/withdraw button in cTrader
2. Token Generation: cTrader backend generates OT token for user context
3. Screen Launch: Broker cashier screen opens with token authentication
4. Transaction Processing: User completes transaction in broker interface
5. Result Communication: Transaction result communicated back to cTrader

Authentication Methods

• Full SSO: Long-term tokens with broker-owned identity
• One-time token handoff: One-time tokens with cTrader identity provider

Implementation Flow

Deposit Flow

Stage 1: User Initiation

1. User clicks deposit button in cTrader

   • Located in cTrader interface (toolbar, menu, or ribbon)
   • Triggers deposit workflow initiation
   • User context available for token generation

2. cTrader backend generates OT token

   • Endpoint: /ctid2/inAppOneTimeToken/data (One-time token handoff)
   • Context: User ID, account info, action type (deposit)
   • Token: Short-lived token for broker authentication

Stage 2: Broker Screen Launch

3. cTrader opens broker deposit screen

   • URL: https://brokerCrmUrl.com/inapp/deposit
   • Parameters: token, account, lang, source, theme
   • Method: Opens in embedded browser/modal within cTrader

4. Broker screen validates token

   • Validation: Verify OT token validity and user context
   • User Identification: Extract user information from token
   • Account Context: Load user's trading accounts

Stage 3: Deposit Processing

5. User selects deposit method and amount

   • Payment method selection (credit card, bank transfer, etc.)
   • Amount entry and currency selection
   • Account selection for deposit destination

6. Broker processes payment transaction

   • Integration with payment provider
   • Transaction validation and processing
   • Real-time status updates

Stage 4: Completion and Communication

7. Transaction completion

   • Payment confirmation received
   • Account balance updated
   • Transaction recorded in broker system

8. Result communication to cTrader

   • Callback: Notify cTrader of successful deposit
   • Balance Update: Update account balance in cTrader
   • User Notification: Show confirmation to user

Withdrawal Flow

Stage 1: User Initiation

1. User clicks withdraw button in cTrader

   • Triggers withdrawal workflow
   • User and account context available

2. cTrader backend generates OT token

   • Similar to deposit flow
   • Action context set to "withdraw"

Stage 2: Broker Screen Launch

3. cTrader opens broker withdrawal screen

   • URL: https://brokerCrmUrl.com/inapp/withdraw
   • Parameters: token, account, lang, source, theme

4. Broker screen validates and pre-loads

   • Token validation and user identification
   • Load available withdrawal methods
   • Display account balances and withdrawal limits

Stage 3: Withdrawal Processing

5. User completes withdrawal request

   • Select withdrawal method
   • Enter withdrawal amount
   • Provide required verification information

6. Broker processes withdrawal

   • Validation of withdrawal request
   • Compliance checks and verification
   • Initiation of withdrawal transaction

Stage 4: Completion and Communication

7. Withdrawal processing

   • Transaction submitted for processing
   • Status tracking and updates
   • Compliance documentation

8. Result communication

   • Withdrawal status communicated to cTrader
   • Account balance updates (if applicable)
   • User notifications and confirmations

API specifications

Broker → cTrader endpoints

Change a trader's balance

Method	URL
POST	/webserv/traders/{login}/changebalance

The broker calls this endpoint after a successful payment to update the trader's balance in cTrader. Append the Manager Token as ?token={webservToken} to the request URL (see Authentication of API calls).

Path parameters

Parameter	Required?	Data Type	Description
login	Yes	integer	The number of a specific trading account.

Request body

Key	Required?	Data Type	Description
comment	No	string	Internal note attached to the balance change. Not shown to retail clients.
externalId	No	string	External identifier of the broker's choosing (e.g., a bank transfer order number).
externalNote	No	string	Brief comment displayed to retail clients.
login	Yes	integer	The number of a specific trading account.
preciseAmount	Yes	double	Amount to deposit or withdraw. Must be a positive decimal number.
source	No	string	Designated source of the deposit or withdrawal.
type	Yes	string	Type of balance change: "DEPOSIT", "WITHDRAW", "DEPOSIT_NONWITHDRAWABLE_BONUS", or "WITHDRAW_NONWITHDRAWABLE_BONUS".

Output

Key	Data Type	Description
balanceHistoryId	integer	Identifier of the balance history entity for the specified trader.

Expected status code: 200

Required Screens

Deposit Screen

• URL: /inapp/deposit
• Parameters: token, account (optional)
• Functionality:
  • Payment method selection
  • Amount entry and validation
  • Account selection
  • Payment processing
  • Transaction confirmation

Withdrawal Screen

• URL: /inapp/withdraw
• Parameters: token, account (optional)
• Functionality:
  • Withdrawal method selection
  • Amount entry with limits validation
  • Verification information collection
  • Withdrawal processing
  • Status tracking

URL Examples

Deposit URLs

<!-- Basic deposit URL -->
https://brokerCrmUrl.com/inapp/deposit?token=abc123&lang=en

<!-- With specific account -->
https://brokerCrmUrl.com/inapp/deposit?token=abc123&account=67890&lang=en

<!-- With theme and source -->
https://brokerCrmUrl.com/inapp/deposit?token=abc123&account=67890&lang=en&theme=dark&source=Mobile

Withdrawal URLs

<!-- Basic withdrawal URL -->
https://brokerCrmUrl.com/inapp/withdraw?token=xyz789&lang=en

<!-- With specific account and theme -->
https://brokerCrmUrl.com/inapp/withdraw?token=xyz789&account=67890&lang=en&theme=light