Trading Platforms (MT4, MT5) Integration

Create Trading Platform Account

This guide explains how to use the Create_TP_Account_Json API endpoint to create a new trading platform (TP) account for an existing client in the Hyper ERP/CRM system.
This function requires a POST request with a JSON payload and proper Bearer token authentication.

Here is an example for function input and output, then we explain all fields: 
//===// Request
{
  "ClientNumber":500014,
  "API_Password":"S0wUqUWvujCf"
}
//===// Response
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "account":{
    "AccountLogin":61436,
    "DataSource":"R1",
    "Platform":"MT4",
    "Status":3,
    "Group":"Basic_IL2",
    "Currency":"USD",
    "Balance":0.00,
    "Equity":0.00,
    "Margin":0.00
  }
}

Request Body

Parameter Type Description
ClientNumber Integer Required. The unique ID of the client. This is the client's
[hyp_Clients].[Client Number]
.
API_Password String Required. The client-specific API password. This password is provided by the system and is stored in the client's website extension record.

Successful Response (HTTP 200)

A successful response will return a ResponseCode of 0 and an `account` object containing the details of the newly created trading platform account.
The `account` object is based on the
[hyp_TPM Account Status]
table and includes the following fields:
Field Type Description
Account Login Integer The new unique Login ID for the trading platform.
Data Source String The identifier for the trading data source (e.g., "R1").
Platform String The name of the trading platform (e.g., "MT5").
Status String The initial status of the account. ENUM: 'Unknown', 'Closed', 'Readonly', 'Active'.
Group String The trading group the account was assigned to.
Currency String The base currency of the trading account, by the group (e.g., "USD").
Balance Money The initial balance of the account (typically 0.00).

Error Responses

Account Already Exists (HTTP 200)

If a trading account already exists for this client, the API will return a ResponseCode of 1 and include the details of the existing account. 
{
  "ResponseCode":1,
  "ResponseMsgEng":"TP account is already exist",
  "account":{
    "AccountLogin":55521,
    "DataSource":"R1",
    "Platform":"MT4",
    "Status":3,
    "Group":"Basic_IL2",
    "Currency":"USD",
    "Balance":18270.84
    "Equity":20000.00,
    "Margin":1200.00
  }
}

Bad Request / Server Errors

These errors occur for invalid input or internal server issues. 
// HTTP 400 Bad Request
{
  "ResponseCode": 99,
  "ResponseMsgEng": "Missing / Wrong Access Token"
}

// HTTP 401 Unauthorized (implied)
{
  "ResponseCode": 11,
  "ResponseMsgEng": "Incorrect API_Password"
}

// HTTP 400 Bad Request
// (e.g., missing JSON body, invalid ClientNumber)
{
  "ResponseCode": 14,
  "ResponseMsgEng": "Bad or missing input data."
}

// HTTP 500 Internal Server Error
// (e.g., failed to load client data from DB)
{
  "ResponseCode": 4,
  "ResponseMsgEng": "Internal server error."
}

// HTTP 500 Internal Server Error
// (The trading platform itself did not respond in time)
{
  "ResponseCode": 5,
  "ResponseMsgEng": "Timeout with no Answer from the Trading System"
}

Deposit of Fiat by Credit card or Bank Transfer

Use the function MT4_Deposit_Fiat_Json to Create a New Receipt doc + JE + Balance order to the MT4.
There is no option to update or delete this action !

Here is an example for function input and output, then we explain all fields: 
//===// Request
{
  "ClientNumber":500155,
  "API_Password":"eBt5yJD3uc12",
  "Ticket_ID":"{F454E096-D080-40FD-A36B-156F4B999124}",
  "BankEnum":1,
  "MethodEnum":1,
  "Currency":"ILS",
  "Amount":3500,
  "USD_ConvertRate":3.2,
  "Time_Stamp":"2026-01-21 08:00:00",
  "End_user_IP":"82.81.138.8"
}
//===// Response
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Receipt_Num":1234
}
Field Data Type Description
ClientNumber Integer Hyper client account number (starting from 500,000).
API_Password String Every account has it's own password.
Ticket_ID String 3rd party system unique ID, string GUID upto 50 chars.
BankEnum Integer Bank account or credit card Row Number from Hyper's table.
Get updated table from
"CC_Banking"
object returned by the Direct_Client_Entity_Json function.
מותג אשראי לא חשוב לנו כי התזרים שלכם זהה לכולם. אבל אם יום אחד יהיה חוזה אחר אז המותג מהטבלה הזאת קובע את יום התזרים.
MethodEnum Integer 1 = Credit Card
2 = Bank Transfer
7 = Bit / Paybox etc
Currency String Credit card debit Currency on client's side. Like ILS or USD etc. Values: 'ILS' or 'USD' only.
Amount Real number Credit card debit Amount on client's side.
USD_ConvertRate Real number USD/ILS rate from Your bank! When the deposit is in USD, pass the value: 1.
Time_Stamp Date + Time UTC value when the credit card transaction was made (does not have to be accurate).
Empty value will make hyper to use current time.
End_user_IP String We need the end (human) client IP address, in which the credit card form was submitted.
Voucher_Number Integer כאשר אתם תסלקו דרך שירות חיצוני. אני צריך את המספר להתאמות אשראי ותיעוד.

Withdrawal of Fiat by Credit card or Bank Transfer

Use the function MT4_Withdrawal_Fiat_Json to Create a New Refund doc + JE. BUT WITHOUT a Balance order to the MT4.
There is no option to update or delete this action !

Here is an example for function input and output, then we explain all fields: 
//===// Request
{
  "ClientNumber":500155,
  "API_Password":"eBt5yJD3uc12",
  "Ticket_ID":"{A1B2C3D4-E5F6-7890-1234-56789ABCDEF0}",
  "BankEnum":1,
  "MethodEnum":1,
  "Currency":"USD",
  "Amount":500,
  "USD_ConvertRate":1,
  "Time_Stamp":"2026-01-21 09:30:00",
  "End_user_IP":"82.81.138.8"
}
//===// Response
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Refund_Num":9876
}
Field Data Type Description
ClientNumber Integer Hyper client account number (starting from 500,000).
API_Password String Every account has it's own password.
Ticket_ID String Required. 3rd party system unique ID, string GUID upto 50 chars. Used to prevent duplicate transactions.
BankEnum Integer Required. Bank account or credit card Row Number from Hyper's table (Banking_StorageTb).
Get updated table from
"CC_Banking"
object returned by the Direct_Client_Entity_Json function.
MethodEnum Integer Required.
1 = Credit Card (Refund)
2 = Bank Transfer
7 = Bit / Paybox etc
Currency String Withdrawal Currency. Values: 'ILS' or 'USD' only.
Amount Real number Withdrawal Amount. Must be greater than 0.
USD_ConvertRate Real number USD/ILS rate. When the withdrawal is in USD, pass the value: 1. Value must be >= 1.
Time_Stamp Date + Time UTC value when the transaction was made.
Empty value or future date is not allowed.
End_user_IP String End (human) client IP address.
Voucher_Number Integer Optional. If the refund is done via external CC clearing, provide the voucher number for reconciliation.

Transaction Already Exists (HTTP 200)

If the system detects that the provided Ticket_ID has already been processed, it returns ResponseCode 30.
The response will include the original document number created in Hyper ERP. 
// For Deposit (Receipt)
{
  "ResponseCode": 30,
  "ResponseMsgEng": "A form with identical information has already been submitted.",
  "Receipt_Num": 10542
}

// For Withdrawal (Refund)
{
  "ResponseCode": 30,
  "ResponseMsgEng": "A form with identical information has already been submitted.",
  "Refund_Num": 9021
}

Direct Balance Order (Deposit/Withdraw) to Trading Platform

Use the function Create_TP_Balance_Order_Json to inject a balance command directly into the Trading Platform (MT4/MT5) command queue.
Unlike the monetary functions above, this function does not create a financial document (Receipt/Refund) or a Journal Entry in the ERP.
It is strictly for balance adjustments, bonuses, or credits directly on the trading account.

Important: This is a synchronous request. The API waits up to 40 seconds for the Trading Platform to confirm the execution.
* ועוד הערה בעברית: בעתיד הקרוב נוסיף קישור למערכת התסריטים לצורך כתיבת פקודות יומן לפעולות כספיות כגון דיבידנד.

Here is an example for function input and output, then we explain all fields: 
//===// Request
{
  "ClientNumber":500155,
  "API_Password":"eBt5yJD3uc12",
  "Ticket_ID":"{F456E096-D080-40FD-A36B-156A4B919124}",
  "Action": "Withdraw",
  "Amount": 100.00,
  "Comment": "Withdrawal request in personal area",
  "Purpose": 4
}
//===// Successful Response (HTTP 200)
{
  "ResponseCode": 0,
  "ResponseMsgEng": "Success",
  "TP_Login": 650021,
  "TP_Order_ID": 8812345
}
Field Data Type Description
ClientNumber Integer Required. Hyper client account number.
API_Password String Required. Client's specific API password.
Action String Required. The operation type.
Values: 'Deposit' or 'Withdraw'.
Ticket_ID String Required. Unique ID for duplicate prevention. If the system detects this ID was already processed, it returns the existing Order ID.
Amount Real Required. The amount to deposit or withdraw. Must be greater than 0.1.
Comment String Required. Free text comment that will appear in the trading platform.
Purpose Integer Optional. Transaction Classification code.
If the value is missing, empty, or not in the list below, the system defaults to 1 = Client Transaction.

Allowed Values:
04 = Fix an Error
05 = Trade Profit/Loss
06 = Fee
07 = First Deposit
08 = Interest
09 = Dividend
10 = Debt Relief
11 = Internal Transfer
12 = Contract Rollover
13 = Admin Fee
* on success: Returns the Trading Platform Login and the Ticket/Order ID generated by the platform.

Specific Error Codes

Code Description
5 Timeout: The API waited 40 seconds but received no confirmation from the Trading System (Automaton). The command might still be in queue.
30 Duplicate: A command with this Ticket_ID already exists. The response will include the original TP_Order_ID.

Credit Card Clearing (Direct Obligate)

Use the function CC_Clearing_Json to send a direct credit card obligate request to the clearing queue.
This function creates a record in
[hyp_Clearing Credit Cards]
and waits (up to ~41 seconds) for the automation response.
Unlike receipt/refund functions, this endpoint does not create Receipt/Refund documents or Journal Entries.

Before calling this function, fetch the available bank/credit-card list and use the row index as BankEnum.
You can get the list from Get_Banks_and_CC_List_Json in the returned object
CC_Banking
.

Here is an example for function input and output, then we explain all fields: 
//===// Request
{
  "ClientNumber":500155,
  "API_Password":"eBt5yJD3uc12",
  "Reference":"{F454E096-D080-40FD-A36B-156F4B999124}",
  "BankEnum":1,
  "Currency":"ILS",
  "Amount":3500,
  "ManualConfirmationCode":""
}
//===// Response
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Req_ID":10452,
  "Result Code":0,
  "Result Text":"Approved",
  "Result CC Brand Name":"Visa",
  "Result Last 4 Digits":"4582",
  "Result Bank Reference":"7091882"
}

Request Body

Field Data Type Description
ClientNumber Integer Required. Hyper client account number.
API_Password String Required. Client API password.
Reference String Required. External reference/transaction ID from your system.
BankEnum Integer Required. Row index from
CC_Banking
.
The selected row must be Website/API-enabled and represent a valid payment profile.
Currency String Required. Values: 'ILS' or 'USD' only.
Amount Real number Required. Charge amount. Must be >= 1.
ManualConfirmationCode String Optional manual approval code from the clearing provider (if available).

Successful Response (HTTP 200)

On technical success, the API returns ResponseCode = 0 and clearing result details.
Important: clearing business result is returned in Result Code and Result Text.
Field Type Description
Req_ID Integer Request ID in
[hyp_Clearing Credit Cards]
.
Result Code Integer Business result from the clearing flow (not HTTP status).
Result Text String Human-readable clearing result message.
Result CC Brand Name String Card brand returned by clearing provider.
Result Last 4 Digits String Last 4 digits of the charged card.
Result Bank Reference String Voucher/reference number returned by the clearing provider.

Timeout Behavior (HTTP 200)

If the automation does not finish within ~41 seconds, the API closes the request and returns:
Result Code = 997 with a timeout text. 
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Req_ID":10453,
  "Result Code":997,
  "Result Text":"The reasonable time for Credit Card Confirmation has passed.",
  "Result CC Brand Name":"",
  "Result Last 4 Digits":"",
  "Result Bank Reference":""
}

Error Responses

// HTTP 400 Bad Request
// Missing / wrong Bearer token
{
  "ResponseCode":99,
  "ResponseMsgEng":"Missing / Wrong Access Token"
}

// HTTP 401 Unauthorized
// Bad client credentials
{
  "ResponseCode":10,
  "ResponseMsgEng":"Bad account credentials (\"ClientNumber\" or \"API_Password\")."
}

// HTTP 400 Bad Request
// Missing or invalid request fields (e.g. wrong Currency, Amount < 1)
{
  "ResponseCode":14,
  "ResponseMsgEng":"Posted fields contain wrong data and/or missing fields."
}

// HTTP 400 Bad Request
// Invalid BankEnum row
{
  "ResponseCode":14,
  "ResponseMsgEng":"Wrong \"BankEnum\" value"
}

// HTTP 400 Bad Request
// Selected payment profile cannot be used by Website/API
{
  "ResponseCode":14,
  "ResponseMsgEng":"This bank account or credit card - cannot be used."
}

// HTTP 500 Internal Server Error
{
  "ResponseCode":4,
  "ResponseMsgEng":"Database Error on server side."
}

Create a Credit Card Form Token

Use the function Create_CC_Frame_Token_Json to generate a secure, one-time usage URL for the credit card entry form.
The generated URL contains a unique token and is designed to be embedded within an iFrame on the client's browser, or as a stand alone page.
To ensure maximum security, the token is valid for a single use only; it is automatically invalidated and deleted from the server the moment the browser makes the first request to the page.

Here is an example for function input and output, then we explain all fields: 
//===// Request
{
  "ClientNumber": 501119,
  "API_Password": "your_api_password_here",
  "Goto_URL": "your.page",
  "Cancel_Btn":True
}
//===// Response
{
  "ResponseCode": 0,
  "ResponseMsgEng": "Success",
  "callurl": "CC_Frame?tok=2B8IDiQL2dO5liUqAS0jzM8xVflhpzLbQBYs..."
}

Request Body

Parameter Type Description
ClientNumber Integer Required. The unique ID of the client in the Hyper ERP system.
API_Password String Required. The client-specific API password for authentication.
Goto_URL String Required. Where to go after this form is done or cancelled.

Response Body

Parameter Type Description
ResponseCode Integer Indicates the result of the request. 0 represents success.
ResponseMsgEng String A textual description of the response status (e.g., "Success").
callurl String [128] The relative path including the one-time token. Append this string to the base API URL to set the src attribute of your iFrame.

Credit Card Entry Frame

The CC_Frame endpoint renders the secure HTML interface where the client inputs their credit card details. This page can be seamlessly embedded within an iFrame on the partner's website, or utilized as a standalone web page during the registration flow.

Session Management & HTTP Redirect

When the browser first loads this page using the one-time token (provided via the tok URL parameter), the server executes a critical Token-to-Cookie conversion process:
  • The one-time token is permanently invalidated.
  • The server sets a secure, HTTP-only HyperSession cookie in the response.
  • To ensure maximum security, the server responds with an HTTP See Other (Redirect) to the exact same URL, but stripped of the tok parameter. This clears the token from the browser's address bar and history.
  • The system binds this session to the specific tenant. All subsequent requests route to the exact same memory instance of the API module. The API instance is kept alive between requests, ensuring high performance and session continuity.

Input Fields & Logical Validation

The HTML form collects standard credit card information. Before any data is stored or processed, the system performs strict logical validations on the server side. If a validation fails, the system halts the process and returns a specific error message to the user.
Field (Mask) Logical Validation Error Message (Constant)
Credit Card Number
mask_cc 		Verifies the length and performs structural validation (e.g., Luhn algorithm) to ensure the card number is mathematically valid. "Please check the credit card number, as it did not pass a logical check."
Valid Month & Year
mask_ccvd 		Validates the MM/YY format and ensures the date represents a current or future period. Expired cards are rejected. "The credit card expiration date must be in the future."
CVV
mask_cvv 		Checks that the input contains exactly 3 digits (or 4 digits, depending on the card brand). "Posted fields contain wrong data and/or missing fields."
ID Number
mask_isrid 		Verifies that the structure and checksum match standard national identification number formats (Control Digit test). "The ID Number did not passed the control digit test."

General & Security Errors

In addition to field-specific validations, the system enforces session and integrity checks:
  • Missing Required Fields: If any mandatory field is left blank, the system returns "Posted fields contain wrong data and/or missing fields."
  • Invalid or Expired Token: If the page is accessed with a token that has already been consumed, or if the token is invalid, the system blocks access and returns "Missing / Wrong Access Token".
  • Timeout: If the session remains idle for too long, the system may return "The reasonable time for Credit Card Confirmation has passed."

Database Storage & Post-Success Flow

Upon successful validation of all inputs, the credit card details are directly saved into the Hyper ERP system's internal Clearing Credit Cards table.
To maintain strict security and PCI compliance, the Credit Card Number is highly encrypted before it is written to the database. The system never stores the plain text of the full credit card number.
After successful storage: If the endpoint is utilized in a standalone mode, the server can gracefully transition the user by responding with a redirect to the next designated URL in the client's onboarding or registration process.
Plus, we forward the last cc record to the endpoint: 
// https://hyper-direct-prod.cglms.com/HyperToColmexIL/CreateCCFromHyper
{
  "ResponseCode":0,
  "CC_Banking":{
    "CreatedOn":"2026-03-29 12:07:31",
    "PaymentMethod":1,
    "DefaultForAutomaticMonetaryTransactions":0,
    "BankId":"",
    "BranchRoutingSwift":"",
    "AccountLocalOrIban":"",
    "AccountOwnerIdNumber":"0356",
    "CcBrandName":"Visa",
    "CcLast4Digits":"9122",
    "RegBankCountry":"",
    "RegBankName":"",
    "RegBankAddress":"",
    "RegAccountOwnerAsContactPerson":"",
    "LastUsage":"",
    "RenewCreditCardOn":"2027-12",
    "LastUpdate":"2026-03-29 12:07:31",
    "EntityFullName":"ירון",
    "AllowToBeUsedByWebsiteApi":0
  }
}