Create Merchant IDs for your EPM accounts over API

Generate Merchant IDs for your Embedded Partner Merchant (EPM) accounts to enable the processing of cryptocurrency or fiat pay-ins and pay-outs through our API.

A Merchant ID (MID) is crucial as it identifies the specific account wallet designated for settling incoming pay-ins. For example, if an MID is linked to a EUR wallet ID, any incoming USDT payment will be automatically converted to EUR and deposited into the associated EUR wallet. Conversely, any outgoing USDT payment will be automatically converted and withdrawn from the same EUR wallet.

MIDs are also responsible for dispatching webhooks, keeping your system updated about any events in a payment's lifecycle.

❗️
Executing API calls on behalf of your Merchant
Ensure you include your EPM's x-account-reference in the API call headers to conduct transactions on behalf of the EPM account, not the Embedded Partner (EP) account.

To create an MID, we will utilize the Create Merchant IDendpoint on the API.

The required information to create an MID for your EPM is as follows:

Field	Description
`displayName`	A distinctive name for this MID for reconciliation purposes.
`webhookUrl`	A static URL for receiving webhook notifications.
`wallet.id`	The ID of the wallet created in the previous step.

Example Request

Here is an example of how to create a Merchant ID through the API:


{
    "displayName": "Main EPM EUR Merchant ID", 
    "webhookUrl": "https://static-webhook.site/12345",
    "wallet": {
        "id": 313675
    }
}

Example Response

After submitting the request to create the Merchant ID, you should expect a response similar to the following:

{
    "id": 27898,
    "merchantId": "855b2c44-b023-485c-98e1-159ef2e4de69",
    "displayName": "Main EPM EUR Merchant ID",
    "secret": "ZmQ1NDFiMTEtY2MyZi00YWI4LTg0ZGQtYzA5YjA4YmRiOTgwMDgzMGUyMjAtZWQ3MC00M2Q5LWJhMmQtY2E2ODc4ZWRjYmYx",
    "webhookUrl": "https://static-webhook.site/12345",
    "defaultExpiryMinutes": 1440,
    "webhookVersion": 1,
    "wallet": {
        "id": 504841,
        "description": "ETH Test Wallet",
        "currency": {
            "id": 1969,
            "code": "ETH",
            "fiat": false,
            "icon": "https://media.dev.node.limited/61a40a06-1e8c-4968-a01a-539587debb3d.png",
            "name": "Ethereum",
            "withdrawalParameters": [],
            "options": {
                "explorer": "https://etherscan.io/",
                "confirmations": 12,
                "address": "https://etherscan.io/address/{{address}}",
                "transaction": "https://etherscan.io/tx/{{hash}}"
            },
            "withdrawalFee": 0.001000000000000000,
            "depositFee": 0,
            "supportsDeposits": true,
            "supportsWithdrawals": true,
            "quantityPrecision": 8,
            "pricePrecision": 5,
            "protocols": [
                {
                    "code": "ETH",
                    "network": "Ethereum"
                }
            ]
        },
        "supportsWithdrawals": true,
        "supportsDeposits": true,
        "custodianWallet": null,
        "supportsThirdParty": false,
        "partner": null,
        "isEmoney": null,
        "protocol": "ETH",
        "address": "0x7be879d34f3Db833f70d9fE4873Bdd0cBcaC6bf6",
        "lookup": null,
        "balance": 0.80568566,
        "available": 0.80568566,
        "withdrawalFee": 0.001000000000000000,
        "depositFee": 0,
        "convertedAvailable": 0,
        "alternatives": [],
        "approxAvailable": "0.80568566",
        "approxBalance": "0.80568566",
        "approxConvertedAvailable": null,
        "capabilities": null
    },
    "emailRecipients": null,
    "autoConvertInvalidPayments": false
}

Key fields in this response to note are:

Field	Description
`merchantId`	The unique ID of the merchant, required for issuing payments or creating payment channels.
`secret`	The key used for hashing the webhook payload, critical for webhook validation.

With a Merchant ID established, you can now initiate multiple payments via the API, ensuring funds are correctly deposited into or withdrawn from the associated wallet.

❗️Executing API calls on behalf of your Merchant

Example Request

Example Response

❗️
Executing API calls on behalf of your Merchant