Table of Contents

https://app.theneo.io/match-trade/match2pay

List of CRMs already integrated with our Crypto Gateway

Utip
FX Back Office
Skale
Trade Smarter
Kenmore design
TradeSoft
Nullpoint
Plugit
Axis
Reltrix
Datalyst
FTT (Fair Trading Technology)

List of payment cashiers already integrated with our Crypto Gateway

Crypto deposit flow #

The client requests a deposit in the broker’s Client Office.
Client Office sends the request to the M2P.
Processing request, generating individual crypto deposit wallet address.
- It is possible to assign generated wallet address to a particular trading account/client. Detailed guide can be found at the bottom.
Returning generated crypto deposit wallet address on the payment page.
- If the client has a cryptocurrency, they can send this cryptocurrency to this individual deposit wallet address.
The transaction is being processed by the blockchain.
After receiving the information from the blockchain about a successfully processed transaction, the cryptocurrency is being booked on the deposit wallet address.
Converting the cryptocurrency to FIAT. The final amount is being added to the broker’s M2P balance.
The amount from a callback is being booked on the client’s trading account.

Documentation #

Deposit #

Key notes #

Under one paymentID there can be more than one transaction.
It’s possible to assign a wallet address to a particular client. If you are interested in this feature, please contact us via the Skype integration group.
On live environment, there is a need to provide IP addresses to whitelist to be able to send requests.

Deposit endpoint: /api/v2/deposit/crypto_agent
HTTP method: POST
Request content: JSON object

Deposit Create Request #

Field Name	Field Type	Description
`amount`	BigDecimal	Functional amount
`currency`	String (required)	Symbol of currency to which `paymentCurrency` should be converted (not full name), e.g. USD
`paymentGatewayName`	String (required)	Name of payment gateway that will be used for deposit list of default payment gateway names
`paymentCurrency`	String (required)	Symbol of currency that will be deposited list of cryptocurrency symbols
`callbackUrl`	String (required)	Notification about changes in payment status will be sent to this URL
`apiToken`	String (required)	API token provided by Match-Trade
`timestamp`	Long (required)	Current time in seconds
`signature`	String (required)	The signature generated from the request body and API secret (more information in section signature generation)
`tradingAccountLogin` (optional)	String (optional)	Depositor’s trading account id

JSON Object Example:

{
"amount" : "10",
"currency" : "USD",
"paymentGatewayName" : "BTC",
"paymentCurrency" : "BTC",
"callbackUrl" : "http://x.pl",
"apiToken" : "b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQS",
"timestamp" : "1566214176",
"signature":"1e0e1de03c8f00177f689cef9e48a9cefab5deb2f572eb578e719ccf2b7f526758ae5aca12b0433d2812908e233a2325"
"tradingAccountLogin":"123456789"
}

Deposit Create Response #

If the field is marked as optional, it doesn’t have to be returned in the callback

Field Name	Field Type	Description
`paymentId`	UUID	Unique id of the payment transaction in the Match2Pay
`status`	Enum	Status of a transaction (available statuses are listed below this table)
`transactionAmount`	BigDecimal	The amount deposited by the client (for this method always 0)
`netAmount`	BigDecimal	Amount after fee charge (for this method always 0)
`transactionCurrency`	String	Symbol of deposited currency list of cryptocurrency symbols
`finalCurrency` (optional)	String	Symbol of currency to which deposited currency was converted
`processingFee`	BigDecimal	Charged fee amount (for this method always 0)
`checkoutUrl`	String	Match2Pay page URL. The client should be redirected to this URL
`address`	String	Cryptocurrency wallet address created for this deposit

Example of JSON response:

{
"paymentId": "99ca8c34-5191-41d9-a1a2-666b9badf1ce",
"status": "NEW",
"transactionAmount": 0,
"netAmount": 0,
"transactionCurrency": "BTC",
"finalCurrency": "USD",
"processingFee": 0,
"address": "C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ",
"checkoutUrl":"http://83.238.162.22:8090/api/payment?id=99ca8c34-5191-41d9-a1a2-666b9badf1ce"
}

Statuses:

STATUS	DESCRIPTION
NEW	The transaction has been initiated (for example, the user displayed the wallet address to deposit)
PENDING	The transaction is processing. This status is temporary. It should change to DONE after receiving confirmation/response from the blockchain
DECLINED	The transaction has failed in the blockchain
DONE	The transaction is done. The funds are booked

Callbacks #

If the field is marked as optional, it doesn’t have to be returned in the callback

Field Name	Field Type	Description
`paymentId`	UUID	Unique id of the payment transaction in the Match2Pay
`status`	Enum	Status of a transaction
`transactionAmount`	BigDecimal	The amount deposited by the client
`netAmount`	BigDecimal	Amount after fee charge
`transactionCurrency`	String	Symbol of deposited currency list of cryptocurrency symbols
`processingFee`	BigDecimal	Charged fee amount
`depositAddress`	String	Cryptocurrency wallet address
`finalAmount` (optional)	BigDecimal	Amount after conversion of the net amount to the desired currency
`finalCurrency` (optional)	String	Symbol of currency to which deposited currency was converted
`conversionRate` (optional)	BigDecimal	Conversion rate from `transactionCurrency` to `finalCurrency`

List of transaction objects #

Field name	Field type	Description
`txid`	String	Blockchain id of the transaction (can be used to check the transaction status in the blockchain)
`confirmations`	Int	Number of transaction confirmations
`amount`	BigDecimal	Deposited amount
`status`	Enum	Transaction status
`processingFee`	BigDecimal	Charged fee amount
`conversionRate`	BigDecimal	Conversion rate from `transactionCurrency` to `finalCurrency`

Examples of JSON responses (deposit with conversion)

The first example (after the client sent funds to the address)

{
"depositAddress":"C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ", 
"cryptoTransactionInfo":
  [
    {
    "txid":"b20feab400c3cd61a9d0daec8526d739a2335fe1900415f24835001e58a837a7",
    "confirmations":0,
    "amount":0.10000000,
    "status":"PENDING",
    "processingFee":0.00500000,
    "conversionRate":0
    }
  ],
"paymentId":"99ca8c34-5191-41d9-a1a2-666b9badf1ce", 
"status":"PENDING",
"transactionAmount":0.10000000,
"netAmount":0.09500000,
"transactionCurrency":"BTC",
"processingFee":0.00500000,
"finalAmount":0,
"finalCurrency":"USD",
"conversionRate":0
}

The second example (after transaction status changed to done)

{
"depositAddress":"C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ",
"cryptoTransactionInfo":
  [
    {
    "txid":"b20feab400c3cd61a9d0daec8526d739a2335fe1900415f24835001e58a837a7",
    "confirmations":2,
    "amount":0.10000000,
    "confirmedTime":"Mar 20, 2019 7:06:38PM",
    "status":"DONE",
    "processingFee":0.00500000,
    "conversionRate":3198.64800
    }
  ],
"paymentId":"99ca8c34-5191-41d9-a1a2-666b9badf1ce",
"status":"DONE",
"transactionAmount":0.10000000,
"netAmount":0.09500000,
"transactionCurrency":"BTC",
"processingFee":0.00500000,
"finalAmount":303.87,
"finalCurrency":"USD",
"conversionRate":3198.65
}

Withdrawals #

Key notes #

In case of a failed transaction, do not use automatic refunds. Please contact us first and we will advise.
On live environment, there is a need to provide IP addresses to whitelist to be able to send requests.

Withdraw Endpoint
Endpoint: /api/v2/withdraw/crypto_agent
HTTP method: POST
Request Content: JSON Object

Withdraw model #

Field Name	Field Type	Description
`currency`	String	Symbol of currency converted to `withdrawCurrency` (not full name), e.g. USD
`paymentGatewayName`	String	Name of payment gateway that will be used for withdrawal list of default payment gateway names
`amount`	BigDecimal	The amount the client wants to withdraw in the `currency`
`withdrawCurrency`	String	Cryptocurrency to which `currency` is converted list of cryptocurrency symbols
`address`	String	User cryptocurrency wallet address to withdraw
`callbackUrl`	String	Notification about changes in payment status will be sent to this URL
`signature`	String	The signature generated from the request body and API secret (more information in section signature generation)
`apiToken`	String	API token provided by Match-Trade
`timestamp`	Long	Current time in seconds
`tradingAccountLogin` (optional)	String	Trading account ID of a user requesting a withdrawal

Example of JSON request

{
"currency":"USD",
"paymentGatewayName": "BTC",
"amount":111.000,
"withdrawCurrency":"BTC",
"address":"1JUzPy6X8EEVQ8oUh8JU1HFdGHX8YYNTxx",
"callbackUrl":"http://54.38.136.76:8080/processing/withdraw/ppcallback",
"signature":"2b5fe7cbfd7d430ac0c6d335a865dfd15809aeedf46d4b91c42f3ef11d3d0ceb3ccb95cc22bb771cce460a362311114a",
"apiToken":"a1QL6yYFt1MLFfCh4UUKOCLR2lhDSPJKE8i9",
"timestamp":1609919778
"tradingAccountLogin":"123456789"
}

Withdrawal statuses:

STATUS	DESCRIPTION
NEW	The transaction has been initiated
ADMIN CONFIRMATION	The transactions need to be confirmed by Match-Trade
PENDING	The transaction is processing. This status is temporary. It should change to DONE or DECLINED after receiving confirmation/response from the blockchain
DECLINED	The transaction has failed. This status is not final – it can be reprocessed within the same paymentID
DONE	The transaction is done. The funds are booked

List of cryptocurrency symbols by network #

Rule: cryptocurrency = paymentCurrency
Eg. for Tether-USDT TRC20 = USX

Bitcoin* – BTC
Ethereum (ERC-20)
- Tether – USDT ERC20 – UST
- USD Coin – USDC ERC20 – UCC
- Ether – ETH
Binance Smart Chain (BEP-20)
- Tether – USDT BEP20 – USB
- USD Coin – USDC BEP20 – USB
- Binance Coin – BNB
TRON (TRC-20)
- Tether – USDT TRC20 – USX (min amount 1 USDT)
- USD Coin – USDC TRC20 – UCX (deposits only, min amount 1 USDC)
- Tronix – TRX (deposits only, min amount 0.00010000 TRX)
POLYGON
- Tether – USDT POLYGON – USP
- USD Coin – USDC POLYGON – UCP
- MATIC – MAT
XRP
- XRP – XRP
Dogecoin
- Dogecoin – DOG
Litecoin
- Litecoin – LTC

*For withdrawals, there are 3 types of BTC addresses supported by our system:

Legacy – starting with “1”
Script – starting with “3”
Segwit – starting with “bc1q”

List of default payment gateway names #

Rule: cryptocurrency = paymentGatewayName
Eg. for Tether TRC20 = USDT TRC20

Bitcoin = BTC
Tether ERC20 = USDT ERC20
USD Coin ERC20 = USDC ERC20
Ether = ETH
Tether BEP20 = USDT BEP20
USD Coin BEP20 = USDC BEP20
Binance Coin = BNB
Tether TRC20 = USDT TRC20
USD Coin TRC20 = USDC TRC20 (deposits only)
Tronix = TRX (deposits only)
Matic = MATIC
USDT Polygon = USDT POLYGON
USDC Polygon = USDC POLYGON
XRP = XRP
Dogecoin = DOGECOIN
Litecoin = LITECOIN

For test environment, we provide Bitcoin and USDT TRC20 gateways.

Signature generation deposit/withdrawal #

All signatures are valid for one minute after creation.

API token and API secret key are provided by Match-Trade.

Algorithm

Take the keys and sort them in A-Z order
Concatenate the values according to the order of keys from the first step
Append the API secret key to the concatenated string from the second step
Build the sha384 hash of the string from the third step

Example

API secret key: MhB6KV2bVlhN6Nud8MRGKQaBTHmwOlgG2Pgj

{
"apiToken" : "b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQS",
"callbackUrl" : "http://test.com",
"currency" : "USD",
"paymentCurrency" : "BTC",
"timestamp" : "1566214818"
}

The string from this request body is: b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQShttp://test.comUSDBTC1566214818
Then we append the secret key at the end and we receive: b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQShttp://test.comUSDBTC1566214818MhB6KV2bVlhN6Nud8MRGKQaBTHmwOlgG2Pgj
Then we use sha-384 to generate a hash from this string and we receive our final signature value: 1e0e1de03c8f00177f689cef9e48a9cefab5deb2f572eb578e719ccf2b7f526758ae5aca12b0433d2812908e233a2325
Please remember that signature must have lowercase letters.
We add it to the request body in the signature field. The final request body is:

{
"apiToken" : "b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQS",
"callbackUrl" : "http://test.com",
"currency" : "USD",
"paymentCurrency" : "BTC",
"signature":"1e0e1de03c8f00177f689cef9e48a9cefab5deb2f572eb578e719ccf2b7f526758ae5aca12b0433d2812908e233a2325",
"timestamp" : "1566214818"
}

Callback signature generation #

Important note: Callback signature should only be validated for status DONE

To check the callback signature, you have to build the sha384 hash by adding content of callback in following order:
“transactionAmount” + “transactionCurrency” + “status” + “apitoken” + “apisecret”
It’s important to mention that signature will be recieved in Headers

Example:

{
  "depositAddress": "mhuLyXBc9CJfFu6KDpsMNaeiqxR5GZzMsH",
  "cryptoTransactionInfo": [
    {
      "txid": "55609bc1c2d3c4746e5f391a226144ed4ab369432adcef617e48d77826a92c1d",
      "confirmations": 1,
      "amount": 0.00011873,
      "confirmedTime": "May 18, 2023 1:51:47 PM",
      "status": "DONE",
      "processingFee": 0.00000119,
      "conversionRate": 27233.9
    }
  ],
  "paymentId": "4d42212c-8ac3-40c1-bc71-0770f522a9a9",
  "status": "DONE",
  "transactionAmount": 0.00011873,
  "netAmount": 0.00011754,
  "transactionCurrency": "BTC",
  "processingFee": 0.00000119,
  "finalAmount": 3.2,
  "finalCurrency": "USD",
  "conversionRate": 27233.9
}
For this case "transactionAmount" + "transactionCurrency" + "status"
string will look like this:

0.00011873BTCDONE +"apitoken"+"apisecret"

amount = 0.00011873
transactionCurrency = BTC
status = DONE
apitoken = provided by Support
apisecret = provided by Support

In case when(USX for Example):
      "amount": 1,
you have to add .00000000 to the ammount. Beginning of string should looks like this:
1.00000000USXDONE

"amount" should allways have 8 decimal places in string to generate signature.

Assigning a wallet address to trading account #

In order to be able to accept multiple deposits to the same wallet address, the integration should be changed so that the payment_id of the generated request is assigned to a particular trading account on your end. The same payment_id should always be used/displayed for a specific trading account within the same crypto gateways

Within one payment_id there may be other deposits, which will have different hashes from the others but will still belong to the same payment_id.

To sum up, the integration on your side should assume that the payment_id of the request may be repeated for deposits, but the transaction hash will be different, so if you receive a callback in which there is a hash with a new transaction it should be booked.

This integration will have to be changed for each crypto payment gateway you use.

Optionally, you can also add the ability to unlink the wallet address (payment_id) from the selected trading account so that it will be possible to generate a new wallet address in exceptional situations.

Match-Trade Technologies

Release notes

Match-Trader

Back Office (CRM)

Match2Pay

Bridge MT4/MT5 with RMS

Hedging

Liquidity

Crypto deposit flow #

Documentation #

Deposit #

Key notes #

Deposit Create Request #

Deposit Create Response #

Callbacks #

List of transaction objects #

Withdrawals #

Key notes #

Withdraw model #

List of cryptocurrency symbols by network #

List of default payment gateway names #

Signature generation deposit/withdrawal #

Callback signature generation #

Assigning a wallet address to trading account #

Match-Trade Technologies is a global company with offices all around the world

Products

About us

Contact us

Knowledge

For media