List of CRMs already integrated with our Crypto Gateway

• Utip
• FX Back Office
• Skale
• Trade Smarter
• Kenmore design
• TradeSoft
• Nullpoint

List of payment cashiers already integrated with our Crypto Gateway

• Paytiko
• Praxis
• BridgerPay

Crypto deposit flow #

1. The client requests a deposit in the broker’s Client Office.
2. Client Office sends the request to the M2P.
3. 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.
4. 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.
   • If the client doesn’t have a cryptocurrency, they can buy it from an exchanger (Moonpay, Itez, Cex.io, Mercuryo) using Credit Card or Wire Transfer.
5. The transaction is being processed by the blockchain.
6. After receiving the information from the blockchain about a successfully processed transaction, the cryptocurrency is being booked on the deposit wallet address.
7. Converting the cryptocurrency to FIAT. The final amount is being added to the broker’s M2P balance.
8. 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 (required)	Depositor’s trading account id

JSON Object Example:

{
"amount" : "10",
"currency" : "USD",
"paymentGatewayName" : "Bitcoin gateway",
"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
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": "Bitcoin gateway",
"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 USD – BUSD – USB
  • Binance Coin – BNB
• TRON (TRC-20)
  • Tether – USDT TRC20 – USX
  • USD Coin – USDC TRC20 – UCX (deposits only)
  • Tronix – TRX (deposits only)

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 USD = BUSD BEP20
• Binance Coin = BNB
• Tether TRC20 = USDT TRC20
• USD Coin TRC20 = USDC TRC20 (deposits only)
• Tronix = TRX (deposits only)

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

For live environment, we provide by default: BTC, BUSD BEP20, and USDT TRC20. Other gateways can be configured on request.

Signature generation #

All signatures are valid for one minute after creation.

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

Algorithm

1. Take the keys and sort them in A-Z order
2. Concatenate the values according to the order of keys from the first step
3. Append the API secret key to the concatenated string from the second step
4. 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"
}

1. The string from this request body is: b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQShttp://test.comUSDBTC1566214818
2. Then we append the secret key at the end and we receive: b3RJ4qBRai129psUfrbGisnE5wpaMaFvovQShttp://test.comUSDBTC1566214818MhB6KV2bVlhN6Nud8MRGKQaBTHmwOlgG2Pgj
3. 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.
4. 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"
}

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.