Match2Pay API documentation

## Sections
• [AI skill.md](https://developers.match2pay.com/ai-skill-md.md): Match2Pay has built a skill that makes integrating our API faster and easier. It lets you connect our API to your system - or check how your current integration is set up - just by describing what you need in plain language to an AI assistant. This skill teaches an AI assistant (like Claude) how to work with the Match2Pay API. Instead of reading technical docs and writing code yourself, you simply say what you want to do, and the assistant handles the technical details for you. To install it: npx skills add https://github.com/Match2Pay-Ltd/M2P-API-skill
• [Integrated systems](https://developers.match2pay.com/integrated-systems.md): CRMs integrated with our Crypto Gateway Utip FX Back Office Skale Trade Smarter Kenmore design TradeSoft Nullpoint Plugit Axis (Broctagon) Reltrix Datalyst FTT (Fair Trading Technology) Leverate Pheasantech UpTrader Syntellicore (Dynamic Works) Delasport TradeCore Payment cashiers integrated with our Crypto Gateway Paytiko Praxis BridgerPay Akurateco Corefy PayProcc Paymaxis Binance Pay Supported wallets (coming soon) Trust Wallet MetaMask Binance Wallet OKX Wallet Bitget Wallet TokenPocket 1inch Wallet Best Wallet And many more...
• [Crypto deposit flow](https://developers.match2pay.com/crypto-deposit-flow.md): Dynamic single-use deposit flow A unique wallet address is generated per deposit request and expires after a time window. The client requests a deposit in the broker’s Client Office. Client Office sends the request to the Match2Pay. Processing request, generating individual crypto deposit wallet address. The Match2Pay system processes the request and generates a unique cryptocurrency deposit wallet address for this individual deposit transaction. IMPORTANT : Wallet addresses must be newly generated each time a client initiates a new deposit. Wallet addresses are single-use only ; if a client deposits to a previously used address at a later time, they risk losing their funds. Displaying the Match2Pay Payment Page to the Client. We strongly recommend that the broker's Client Office redirects the client to the Match2Pay payment page or displays it in an Iframe. IMPORTANT : Generated wallet address has an expiration time. Currently, this is set to 2 hours for Bitcoin (BTC) deposits and 30 minutes for all other cryptocurrencies. Clients must ensure their deposit is made to the provided address within this specific time window for the transaction to be processed successfully . A 12-hour post-expiration grace period applies, deposits confirmed on-chain within this window will still be accepted and processed. 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 Match2Pay balance. The amount from a callback is being booked on the client’s trading account. An important benefit of this solution is that, unlike the Static Wallet flow, there is no minimum fee applied to deposits. If you are unable to ensure that a unique wallet address is generated for each client deposit, or if you cannot integrate our payment page, please contact Match2Pay support. Static wallet flow (set by default) A reusable wallet address is assigned to a specific trading account; multiple deposits can be sent to the same address. The client requests a deposit in the broker’s Client Office. Client Office sends the request to the Match2Pay. 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 Match2Pay balance. The amount from a callback is being booked on the client’s trading account. To correctly handle multiple deposits to the same static wallet address, your integration must be adapted as follows: Assign payment_id : The payment_id generated with the first deposit request must be assigned and stored for a particular client account on your end. Reuse payment_id : For all future deposit requests from that same client (within the same crypto gateway), you must use/display the same, originally assigned payment_id . Handle Callbacks Correctly: A single payment_id will be associated with multiple deposits. Each deposit will have a unique transaction hash. Your system must process incoming callbacks by checking for a new, unbooked transaction hash. If you receive a callback with a known payment_id but a new hash, the transaction should be booked. Gateway-Specific Implementation: This integration logic must be applied separately for each crypto payment gateway you use. Optional - Unlink Wallet: You can optionally add a feature to unlink the wallet address ( payment_id ) from a selected account. This would allow a new wallet address to be generated for that client in exceptional situations.
• [Deposit Request](https://developers.match2pay.com/deposit-request.md): This request is responsible for generating a new deposit wallet address for cryptocurrency transactions and providing a link to the payment page. It is a valuable tool for users who wish to make a deposit or payment using cryptocurrencies. Important information: On live environment, there is a need to provide IP addresses to whitelist to be able to send requests Under one paymentID there can be more than one transaction. Crypto selection flow (2-step payment page) When a deposit request is created without a preselected cryptocurrency ( "paymentCurrency" and "paymentGatewayName" ), the user is redirected to a two-step payment page: Step I – Cryptocurrency selection – the user chooses which currency to use. Step II – Payment details – the user sees the address, amount and completes the deposit. The user may navigate back from Step II to Step I to select a different cryptocurrency. In this case, a single deposit request can have multiple deposit addresses associated with it, one per selected cryptocurrency. If "paymentCurrency" and "paymentGatewayName" are provided, the user is redirected directly to the payment details. Fixed wallet By default, Match2Pay generates a new deposit address for each deposit request. For gateways using the "CRYPTO_AGENT" method, it is possible to enable the fixed wallets feature on the gateway configuration level When fixed wallets are enabled : Match2Pay checks if there is an existing deposit address for the given client email - "email" parameter. If an address exists, the same deposit address is returned. If not, a new deposit address is generated and linked to this email for future requests. Deposit endpoint: /api/v2/payment/deposit HTTP method: POST Request content: JSON object Binance Pay integration: To use the Binance Pay gateway, you must set "paymentGatewayName" parameter to “USDT_BINANCE” and set the “paymentCurrency” parameter to “USX” . Note: This configuration unlocks multiple cryptocurrency options for the user on the payment page. Statuses of deposit requests Title 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 and passing the compliance verification. DECLINED This status may be assigned automatically by our scoring system if the transaction does not pass compliance verification. FAIL The transaction has failed in the blockchain or an error occurred while it was being processed. DONE The transaction is done. The funds are booked . SUSPECTED The transaction is under review by our scoring system. This status indicates that additional compliance verification is required before the transaction can be processed further. PARTIALLY PAID The received amount is less than the requested amount. An additional payment covering the missing balance is required for the transaction status to change to DONE . REVERSED The transaction has been reversed after being rejected by the scoring system and assigned a DECLINED status. This action can be performed by an authorized administrator through the Compliance Rejections section, allowing the transaction to proceed despite the initial rejection.
• [Deposit Callbacks](https://developers.match2pay.com/deposit-callbacks.md): Match2Pay sends a callback to your callbackUrl every time the status of a deposit changes. Each status below has its own subsection with an example callback body. DONE - the transaction is done and the funds are booked. PENDING - the transaction appeared in the blockchain and is being processed. This status is temporary and changes to DONE after blockchain confirmation and compliance verification. PARTIALLY_PAID - the received amount is lower than the requested one. An additional payment covering the missing balance is required for the status to change to DONE. FAIL - the transaction failed in the blockchain or an error occurred while it was being processed. DECLINED - the transaction was rejected, e.g. it did not pass compliance verification. The same status is sent when a declined deposit is reversed.
  • [DONE](https://developers.match2pay.com/deposit-callbacks/done.md): The transaction is done and the funds are booked on the merchant's balance. This callback is sent after the funds are correctly booked.
  • [PENDING](https://developers.match2pay.com/deposit-callbacks/pending.md): Sent after the transaction appears in the blockchain. The transaction is being processed. This status is temporary and changes to DONE after blockchain confirmation and compliance verification.
  • [PARTIALLY_PAID](https://developers.match2pay.com/deposit-callbacks/partially_paid.md): The received amount is lower than the requested one. An additional payment covering the missing balance is required for the status to change to DONE.
  • [FAIL](https://developers.match2pay.com/deposit-callbacks/fail.md): The transaction failed in the blockchain or an error occurred while it was being processed.
  • [DECLINED](https://developers.match2pay.com/deposit-callbacks/declined.md): The transaction was rejected, e.g. it did not pass compliance verification. The same status is sent when a declined deposit is reversed.
• [Withdrawal Request](https://developers.match2pay.com/withdrawal-request.md): A withdrawal request is a fundamental process that facilitates the transfer of cryptocurrency funds from one's wallet to an external recipient's address. Endpoint: /api/v2/payment/withdrawal HTTP method: POST Request Content: JSON Object Statuses of withdrawal requests Title Description NEW The transaction has been initiated . ADMIN CONFIRMATION The transaction needs to be confirmed by Support . PENDING The transaction is processing. This status is temporary. It should change to DONE or DECLINED after receiving confirmation/response from the blockchain and compliance verification system. DECLINED The transaction has been rejected. This status mainly occurs in these scenarios: - a transaction requiring admin confirmation is declined by an authorized administrator or by our team. - the transaction does not pass compliance verification. - there are not enough funds on the merchant balance to process the transaction. DONE The transaction is done. The funds are booked . FAIL The transaction has failed . This status is not final – it can be reprocessed within the same paymentID.
• [Withdrawal Callbacks](https://developers.match2pay.com/withdrawal-callbacks.md): Match2Pay sends a callback to your callbackUrl every time the status of a withdrawal changes. Each status below has its own subsection with an example callback body. DONE - the transaction is confirmed on-chain and the funds are booked. PENDING - the transaction appeared in the blockchain and is being processed. This status is temporary and changes to DONE or DECLINED after blockchain confirmation and compliance verification. ADMIN_CONFIRMATION - the request is waiting for confirmation by an authorized administrator or Support. FAIL - the transaction has failed. This status is not final - it can be reprocessed within the same paymentId. DECLINED - the transaction was rejected: declined by an administrator or our team, did not pass compliance verification, or there are not enough funds on the merchant balance.
  • [DONE](https://developers.match2pay.com/withdrawal-callbacks/done.md): The transaction is confirmed on-chain and the funds are booked.
  • [PENDING](https://developers.match2pay.com/withdrawal-callbacks/pending.md): Sent after the transaction appears in the blockchain. The transaction is being processed. This status is temporary and changes to DONE or DECLINED after blockchain confirmation and compliance verification.
  • [ADMIN_CONFIRMATION](https://developers.match2pay.com/withdrawal-callbacks/admin_confirmation.md): The request is waiting for confirmation by an authorized administrator or Support.
  • [FAIL](https://developers.match2pay.com/withdrawal-callbacks/fail.md): The transaction has failed. This status is not final - it can be reprocessed within the same paymentId.
  • [DECLINED](https://developers.match2pay.com/withdrawal-callbacks/declined.md): The transaction was rejected: declined by an administrator or our team, did not pass compliance verification, or there are not enough funds on the merchant balance.
• [Cryptocurrency details](https://developers.match2pay.com/cryptocurrency-details.md): Please make sure you send cryptocurrency from the list below and use a network supported by Match2pay. Sending funds via an unsupported token or network may result in loss of funds. Title Description Title cryptocurrency paymentCurrency paymentGatewayName Bitcoin BTC BTC Ethereum (only Ethereum network) ETH ETH USDT ERC20 (only Ethereum network) min amount 5 USDT! UST USDT ERC20 USDC ERC20 (only Ethereum network) min amount 5 USDC! UCC USDC ERC20 DAI ERC20 (only Ethereum network) DAE DAI ERC20 SHIBA INU ERC20 [Deposits only] SHB SHIBA INU ERC20 BTC ERC20 [Deposits only] BTE BTC ERC20 Coinbase Wrapped BTC ERC20 [Deposits only] CTC CBBTC ERC20 Tronix - TRX [Deposits only] min amount 1.5 TRX! TRX TRX USDT TRC20 - min amount 1 USDT! USX USDT TRC20 Binance Coin (only BSC network) BNB BNB USDT BEP20 (only BSC network) USB USDT BEP20 USDC BEP20 (only BSC network) UCB USDC BEP20 DAI BEP20 (only BSC network) DAB DAI BEP20 BTC BEP20 [Deposits only] BTB BTC BEP20 ETH BEP20 [Deposits only] ETB ETH BEP20 SHIBA INU BEP20 [Deposits only] SHH SHIBA INU BEP20 MATIC [Deposits only] MAT MATIC USDT Polygon USP USDT POLYGON USDC Polygon [Deposits only] UCP USDC POLYGON DAI Polygon DAP DAI POLYGON XRP [Deposits only] XRP XRP Dogecoin [Deposits only] DOG DOGECOIN Litecoin LTC LTC Solana [Deposits only] SOL SOL USDT Solana USS USDT SOL USDC Solana UCS USDC SOL DAI Solana DAS DAI SOLANA ETH BASE [Deposits only] BST ETH BASE USDC BASE UBC USDC BASE USDT BASE [Deposits only] UTB USDT BASE ETH OPTIMISM [Deposits only] ETO ETH OPTIMISM USDT OPTIMISM UTO USDT OPTIMISM USDC OPTIMISM UCO USDC OPTIMISM ETH ARBITRUM [Deposits only] ETA ETH ARBITRUM USDT ARBITRUM UTA USDT ARBITRUM USDC ARBITRUM UCA USDC ARBITRUM BNB OPBNB [Deposits only] BNO BNB OPBNB USDT OPBNB [Deposits only] USO USDT OPBNB Binance Pay (multiple currencies) [Deposits only] USX USDT_BINANCE 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” For the test environment, we provide Bitcoin and USDT TRC20 gateways. For withdrawals, Match2Pay supports both options: with or without a memo. To withdraw without a memo, simply enter the wallet address as usual. If a memo is required, use the format walletAddress;memo , for example: "address": "UQANXiRA9BhsOAcuaQ30L7W2StlboH2p9_eOxf4VB1ohz0v6;1708317974"
• [Extended callback signature generation](https://developers.match2pay.com/extended-callback-signature-generation.md): Important note: Callback extended signature will be sent for every status and transaction type. To ensure that a callback sent from the Match2Pay system wasn't already used for transaction verification you can optionally check the extended callback signature. To do this you have to build the HMAC-SHA384 hash by adding the callback's full body content and API secret in this order: { raw callback body without white spaces } + ‘apisecret’ It's important to mention that signature will be received in Headers under X-M2P-Extended-Signature field. Example: In this case { raw callback body without white spaces } + ‘apisecret’ string will look like this: {"depositAddress":"mhuLyXBc9CJfFu6KDpsMNaeiqxR5GZzMsH","cryptoTransactionInfo":[{"txid":"55609bc1c2d3c4746e5f391a226144ed4ab369432adcef617e48d77826a92c1d","confirmations":1,"amount":0.00011873,"confirmedTime":"May18,20231:51:47PM","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}apisecret The HMAC-SHA384 hash built with this string will look like this: 73a65b2c22174d71ece96072193a8ee67b8c0f81e58444e7d0c1fd79a90308186c33c4c6800345d8369a20cb608c0f53
• [Request signature generation](https://developers.match2pay.com/request-signature-generation.md): All signatures are valid for one minute after creation. API token and API secret key are provided by Match-Trade. Algorithm Take all the keys from your deposit or withdrawal request 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: ApiSecretProvidedBySupport Plain text { "amount": 10, "apiToken": "ApiTokenProvidedBySupport", "callbackUrl": "http://test/deposit/callback", "currency": "USD", "customer": { "firstName": "firstName_4da0af01617c", "lastName": "lastName_801eb285edd1", "address": { "address": "address_52c10ed842fb", "city": "city_62da6faaeb17", "country": "country_a6be7ed127cc", "zipCode": "zipCode_3e168862ef49", "state": "state_b8d531055c90" }, "contactInformation": { "email": "email_e4ac63093536", "phoneNumber": "phoneNumber_8fcb0237f7ee" }, "locale": "en_US", "dateOfBirth": "dateOfBirth_338c08d95dd6", "tradingAccountLogin": "clientId_d6811bff2963", "tradingAccountUuid": "clientUid_56b798ba2ae2" }, "failureUrl": "http://test/failed-payment", "paymentCurrency": "USX", "paymentGatewayName": "USDT TRC20", "paymentMethod": "CRYPTO_AGENT", "successUrl": "http://test/thanku", "timestamp": "1764149779000" } { "amount": 10, "apiToken": "ApiTokenProvidedBySupport", "callbackUrl": "http://test/deposit/callback", "currency": "USD", "customer": { "firstName": "firstName_4da0af01617c", "lastName": "lastName_801eb285edd1", "address": { "address": "address_52c10ed842fb", "city": "city_62da6faaeb17", "country": "country_a6be7ed127cc", "zipCode": "zipCode_3e168862ef49", "state": "state_b8d531055c90" }, "contactInformation": { "email": "email_e4ac63093536", "phoneNumber": "phoneNumber_8fcb0237f7ee" }, "locale": "en_US", "dateOfBirth": "dateOfBirth_338c08d95dd6", "tradingAccountLogin": "clientId_d6811bff2963", "tradingAccountUuid": "clientUid_56b798ba2ae2" }, "failureUrl": "http://test/failed-payment", "paymentCurrency": "USX", "paymentGatewayName": "USDT TRC20", "paymentMethod": "CRYPTO_AGENT", "successUrl": "http://test/thanku", "timestamp": "1764149779000" } The string from this request body is: 10ApiTokenProvidedBySupporthttp://test/deposit/callbackUSD{firstName=firstName_4da0af01617c, lastName=lastName_801eb285edd1, address={address=address_52c10ed842fb, city=city_62da6faaeb17, country=country_a6be7ed127cc, zipCode=zipCode_3e168862ef49, state=state_b8d531055c90}, contactInformation={email=email_e4ac63093536, phoneNumber=phoneNumber_8fcb0237f7ee}, locale=en_US, dateOfBirth=dateOfBirth_338c08d95dd6, tradingAccountLogin=clientId_d6811bff2963, tradingAccountUuid=clientUid_56b798ba2ae2}http://test/failed-paymentUSXUSDT TRC20CRYPTO_AGENThttp://test/thanku1764149779000 Then we append the secret key at the end and we receive: 10ApiTokenProvidedBySupporthttp://test/deposit/callbackUSD{firstName=firstName_4da0af01617c, lastName=lastName_801eb285edd1, address={address=address_52c10ed842fb, city=city_62da6faaeb17, country=country_a6be7ed127cc, zipCode=zipCode_3e168862ef49, state=state_b8d531055c90}, contactInformation={email=email_e4ac63093536, phoneNumber=phoneNumber_8fcb0237f7ee}, locale=en_US, dateOfBirth=dateOfBirth_338c08d95dd6, tradingAccountLogin=clientId_d6811bff2963, tradingAccountUuid=clientUid_56b798ba2ae2}http://test/failed-paymentUSXUSDT TRC20CRYPTO_AGENThttp://test/thanku1764149779000ApiSecretProvidedBySupport Then we use sha-384 to generate a hash from this string and we receive our final signature value: e058a6fb0d310335985f69d686ae47bdf1c34ad33bcafd83852b6034d8eb3254e7d300a63590f815baf2fe3d8eff11ec Please remember that signature must have lowercase letters . We add it to the request body in the signature field. The final request body is: Plain text { "amount": 10, "apiToken": "ApiTokenProvidedBySupport", "callbackUrl": "http://test/deposit/callback", "currency": "USD", "customer": { "firstName": "firstName_4da0af01617c", "lastName": "lastName_801eb285edd1", "address": { "address": "address_52c10ed842fb", "city": "city_62da6faaeb17", "country": "country_a6be7ed127cc", "zipCode": "zipCode_3e168862ef49", "state": "state_b8d531055c90" }, "contactInformation": { "email": "email_e4ac63093536", "phoneNumber": "phoneNumber_8fcb0237f7ee" }, "locale": "en_US", "dateOfBirth": "dateOfBirth_338c08d95dd6", "tradingAccountLogin": "clientId_d6811bff2963", "tradingAccountUuid": "clientUid_56b798ba2ae2" }, "failureUrl": "http://test/failed-payment", "paymentCurrency": "USX", "paymentGatewayName": "USDT TRC20", "paymentMethod": "CRYPTO_AGENT", "successUrl": "http://test/thanku", "timestamp": "1764149779000", "signature": "e058a6fb0d310335985f69d686ae47bdf1c34ad33bcafd83852b6034d8eb3254e7d300a63590f815baf2fe3d8eff11ec" } { "amount": 10, "apiToken": "ApiTokenProvidedBySupport", "callbackUrl": "http://test/deposit/callback", "currency": "USD", "customer": { "firstName": "firstName_4da0af01617c", "lastName": "lastName_801eb285edd1", "address": { "address": "address_52c10ed842fb", "city": "city_62da6faaeb17", "country": "country_a6be7ed127cc", "zipCode": "zipCode_3e168862ef49", "state": "state_b8d531055c90" }, "contactInformation": { "email": "email_e4ac63093536", "phoneNumber": "phoneNumber_8fcb0237f7ee" }, "locale": "en_US", "dateOfBirth": "dateOfBirth_338c08d95dd6", "tradingAccountLogin": "clientId_d6811bff2963", "tradingAccountUuid": "clientUid_56b798ba2ae2" }, "failureUrl": "http://test/failed-payment", "paymentCurrency": "USX", "paymentGatewayName": "USDT TRC20", "paymentMethod": "CRYPTO_AGENT", "successUrl": "http://test/thanku", "timestamp": "1764149779000", "signature": "e058a6fb0d310335985f69d686ae47bdf1c34ad33bcafd83852b6034d8eb3254e7d300a63590f815baf2fe3d8eff11ec" } Algorithm for creating the signature This Python script generates a SHA-384 signature from a structured request body and an API secret. It is designed to ensure data integrity by concatenating specific request parameters in a defined order and hashing them.
• [Onchain Fee](https://developers.match2pay.com/onchain-fee.md): Onchain fees are charges associated with processing cryptocurrency transactions on their respective blockchain networks. Match2Pay applies fixed onchain fees to: Direct settlement withdrawals Client withdrawals , if specified in the agreement Cryptocurrency Network Onchain Fee BTC Bitcoin 0.00004 BTC ETH Ethereum 0.001 ETH BNB Binance Chain 0.0005 BNB MATIC Polygon 0.5 MATIC Stablecoin Network Onchain Fee USDT TRC20 2.5 USDT USDT BEP20 1 USDT USDT ERC20 2.5 USDT USDT POLYGON 1 USDT USDC BEP20 1 USDC USDC ERC20 2.5 USDC USDC POLYGON 1 USDC