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.

Request Body

The request must be sent with a `Content-Type: application/json` header. The JSON payload must contain the client's ID and their specific API password.

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.


{
  "ClientNumber":500014,
  "API_Password":"S0wUqUWvujCf"
}

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).


{
  "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
  }
}

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, 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, 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

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

Request Body

The request must be sent with a POST and Content-Type: application/json.

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).

//===// Request
{
  "ClientNumber":500155,
  "API_Password":"eBt5yJD3uc12",
  "Reference":"{F454E096-D080-40FD-A36B-156F4B999124}",
  "BankEnum":1,
  "Currency":"ILS",
  "Amount":3500,
  "ManualConfirmationCode":""
}

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.

{
  "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"
}

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."
}