match2pay-v2

## Sections
• [AI skill.md](https://app.theneo.io/match-trade/match2pay-v2/integrated-systems-copy.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://app.theneo.io/match-trade/match2pay-v2/integrated-systems.md): List of CRMs already 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 List of payment cashiers already integrated with our Crypto Gateway Paytiko Praxis BridgerPay Akurateco Corefy PayProcc Paymaxis Binance Pay List of 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://app.theneo.io/match-trade/match2pay-v2/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 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. 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. Title Feature Key Differences Dynamic single-use deposit flow Static wallet flow Wallet address generation Merchant’s Client Office requests a brand-new deposit address from Match2Pay Merchant’s Client Office generates a wallet address which they can save Wallet Address Usage Single-use per transaction. Address is released back to the pool after successful completion or expiration Multi-use. Client can deposit to the same saved address multiple times Consequence of Reusing Old Address by Client Risk of fund loss. Client should NEVER reuse a previously generated wallet address. Once an address is returned to the pool it can be reassigned to a different client No risk, if client deposit to previously generated wallet address Address Expiration Yes. 30 minutes (2 hours for Bitcoin) + an additional 12-hour window for deposit No expiration time for the client's generated wallet address Minimum Deposit Fees No minimal fees for deposits Minimal deposit fees for: USDT ERC20 - 5$ ; USDC ERC20 - 5$ ; USDT TRC20 - 1$ ; ETH - 0.001 ETH Payment Page Integration Strongly recommended. Merchants's Client Office redirects to Match2Pay payment page or displays it in an Iframe on every deposit Client can send funds directly to the wallet address saved to his trading account
• [Deposit Request](https://app.theneo.io/match-trade/match2pay-v2/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 Informations: 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 payment is not provided, a 2-step payment page with cryptocurrency selection will be generated: If "paymentCurrency" and "paymentGatewayName" are not provided, a 2-step payment page will be generated: 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 intefration: To use the Binance Pay gateway, you must set "paymentGatewayName" parameter to “BNB_BINANCE” and set the “paymentCurrency” parameter to “BNB” . 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 REJECTED The transaction has been rejected. This usually occurs when a transaction requiring admin confirmation is declined by an authorized administrator or by our team. This status may also be assigned automatically by our scoring system if the transaction does not pass compliance verification. DECLINED The transaction has failed in the blockchain 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. This action can be performed by an authorized administrator through the Compliance Rejections section, allowing the transaction to proceed despite the initial rejection.
• [Callbacks](https://app.theneo.io/match-trade/match2pay-v2/callbacks.md): The first callback will be sent to you after transaction appears in blockchain - PENDING status Plain text { "depositAddress":"C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ", "cryptoTransactionInfo": [ { "txid":"b20feab400c3cd61a9d0daec8526d739a2335fe1900415f24835001e58a837a7", "confirmations":0, "amount":0.10000000, "transactionCurrency": "BTC", "status":"PENDING", "processingFee":0.00500000, "conversionRate":0 "blockchainType": "BITCOIN" } ], "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, "settlementCurrency": null, "settlementAmount": null } { "depositAddress":"C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ", "cryptoTransactionInfo": [ { "txid":"b20feab400c3cd61a9d0daec8526d739a2335fe1900415f24835001e58a837a7", "confirmations":0, "amount":0.10000000, "transactionCurrency": "BTC", "status":"PENDING", "processingFee":0.00500000, "conversionRate":0 "blockchainType": "BITCOIN" } ], "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, "settlementCurrency": null, "settlementAmount": null } The second callback will be sent to you after the funds are correctly booked - DONE status Plain text { "depositAddress":"C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ", "cryptoTransactionInfo": [ { "txid":"b20feab400c3cd61a9d0daec8526d739a2335fe1900415f24835001e58a837a7", "confirmations":2, "amount":0.10000000, "transactionCurrency": "BTC", "confirmedTime":"Mar 20, 2019 7:06:38PM", "status":"DONE", "processingFee":0.00500000, "conversionRate":3198.64800 "blockchainType": "BITCOIN" } ], "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, "settlementCurrency": "USD", "settlementAmount":303.87 } { "depositAddress":"C9wic7ex7etARjPGQPKBHGLr2cRcCD17aZ", "cryptoTransactionInfo": [ { "txid":"b20feab400c3cd61a9d0daec8526d739a2335fe1900415f24835001e58a837a7", "confirmations":2, "amount":0.10000000, "transactionCurrency": "BTC", "confirmedTime":"Mar 20, 2019 7:06:38PM", "status":"DONE", "processingFee":0.00500000, "conversionRate":3198.64800 "blockchainType": "BITCOIN" } ], "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, "settlementCurrency": "USD", "settlementAmount":303.87 } Fields Title Description depositAddress Cryptocurrency wallet address txid Blockchain id of the transaction (can be used to check the transaction status in the blockchain) confirmations Number of transaction confirmations amount Deposited amount status Transaction status processingFee Charged fee amount conversionRate Conversion rate from transactionCurrency to finalCurrency paymentId Unique id of the payment transaction in the Match2Pay transactionAmount Value of transactions in the transactions currency That value should NOT be used to book deposits netAmount transactionAmount after processsing fee deduction finalAmount Amount sum of confirmed transactions finalCurrency Currency in which we will return the finalAmount settlementCurrency Currency in which transaction will be booked on Match2Pay balance settlementAmount Amount that will be booked on Match2Pay balance
• [Withdrawal Request](https://app.theneo.io/match-trade/match2pay-v2/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 Title Description NEW The transaction has been initiated ADMIN CONFIRMATION The transactions need 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 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 FAIL The transaction has failed
• [Cryptocurrency details](https://app.theneo.io/match-trade/match2pay-v2/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 or withdrawCurrency 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 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 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] BNB BNB_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"
• [Callback signature generation](https://app.theneo.io/match-trade/match2pay-v2/callback-signature-generation.md): Important note : Callback signature should only be validated for status DONE To ensure that callback comes from match2pay system you can optionally check the callback signature. To do this you have to build the sha384 hash by adding the content of callback in following order: “transactionAmount” + “transactionCurrency” + “status” + “apitoken” + “apisecret” It’s important to mention that signature will be recieved in Headers Example: In 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 amount. Beginning of string should looks like this: 1.00000000USXDONE "amount" should allways have 8 decimal places in string to generate signature.
• [Signature](https://app.theneo.io/match-trade/match2pay-v2/signature.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" } 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: 10.00ApiTokenProvidedBySupporthttp://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" } Algorithm for creating the siganture 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://app.theneo.io/match-trade/match2pay-v2/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