Guides

Direct Payin API Guide

This guide provides detailed instructions for integrating a payment processing API. It includes essential endpoints for initiating payments and managing payment results.

📘

Before using the feature:

  1. Complete KYC.
  2. Purchase a subscription plan, which includes the payin function.
  3. Make sure the Retrieve User Information endpoint does not return the payin_mercuryo_forbidden scope.

Step 1. Get Available Currencies

Endpoint

GET /currency/currency

Description

This endpoint retrieves a list of all supported currencies along with their detailed information, including associated tokens.

If, in the response of the endpoint, a currency features the DIRECT_PAYIN flag, it means that this currency can be used for paying operations.

Response Example:

  {
    "id": 0,  // unique identifier of the currency.
    "slug": "string",  // unique identifier (slug) of the currency.
    "shortName": "string",  // short name of the currency.
    "description": "string",  // description of the currency.
    "type": "string",  // type of the currency (e.g., fiat, crypto).
    "decimals": 0,  // number of decimal places the currency supports.
    "iconUrl": "string",  // URL to the currency's icon.
    "totalsPrecision": 0,  // precision for total calculations.
    "roundingPrecision": 0,  // rounding precision.
    "eurPrice": "9.87",  // price of the currency in EUR.
    "settings": {
      "enabled": true,  // indicates if the currency is enabled.
      "partner": "string",  // partner code associated with the currency.
      "group": "string",  // group code associated with the currency.
      "walletEnabled": true,  // indicates if wallet functionality is enabled.
      "transferEnabled": true,  // indicates if transfers are enabled.
      "transferFeePercent": 0,  // percentage fee for transfers.
      "transferFeeFixed": 0,  // fixed fee for transfers.
      "transferFeeMin": 0,  // minimum transfer fee.
      "transferFeeMax": 0, // maximum transfer fee.
      "features": "DIRECT_PAYIN"
    },
    "tokens": [
      {
        "id": 0,  // unique identifier of the token.
        "name": "string",  // name of the token.
        "slug": "string",  // unique identifier (slug) of the token.
        "address": "string",  // blockchain address of the token.
        "decimals": 0,  // number of decimal places the token supports.
        "nativeSign": true,  // indicates if the token has native support for signing.
        "minConsolidation": 0,  // minimum consolidation amount for the token.
        "blockchain": {
          "id": 0,  // unique identifier of the blockchain.
          "name": "string",  // name of the blockchain.
          "slug": "string",  // unique identifier (slug) of the blockchain.
          "explorer": "string"  // URL to the blockchain explorer.
        },
        "settings": {
          "partner": "string",  // partner code associated with the token.
          "group": "string",  // group code associated with the token.
          "depositEnabled": true,  // indicates if deposits are enabled.
          "depositFeePercent": 0,  // percentage fee for deposits.
          "depositFeeFixed": 0,  // fixed fee for deposits.
          "depositFeeMin": 0,  // minimum deposit fee.
          "depositFeeMax": 0,  // maximum deposit fee.
          "withdrawEnabled": true,  // indicates if withdrawals are enabled.
          "withdrawFeePercent": 0,  // percentage fee for withdrawals.
          "withdrawFeeFixed": 0,  // fixed fee for withdrawals.
          "withdrawFeeMin": 0,  // minimum withdrawal fee.
          "withdrawFeeMax": 0  // maximum withdrawal fee.
        }
      }
    ]
  }

Step 2. Get Available Payin Rates and Limits

Endpoint

GET /wallet/direct-payin/rates-and-limits

Description

This endpoint provides the current rate along with minimum and maximum currency amounts allowed for this type of transaction for the selected currency pair.

Query Parameters

NameTypeRequiredDescription
fromCurrencystring✅The original currency of the amount before conversion. Defaults to USD
toCurrencystring✅The destination currency after conversion: e.g. USDT, ETH, SOL, BTC.

Response Example

{
  "maxCrypto": 0.37565671,
  "maxFiat": 936.92,
  "minCrypto": 0.00447761,
  "minFiat": 11.72,
  "rate": 2496.02000000
}

Step 3. Initiate a Payin Operation

Endpoint

POST /wallet/direct-payin

Description

The endpoint initiates a payin operation to deposit funds in the specified currency to the user's account.

Query Parameters:

NameTypeRequiredDescription
dryRunboolean➖This parameter allows to check resulting rate and fee amount without executing any operation. If true, the API simulates the operation without executing it. This allows you to preview exchange rates, fees, and other details before committing. The actual operation will only proceed if dryRun is omitted or explicitly set to false.

Body Parameters

NameTypeRequiredDescription
accountuuid✅Identifier of the CHECKING- type account associated with the payin.
fromCurrencystring✅The original currency of the amount before conversion. Defaults to USD
toCurrencystring✅The destination currency after conversion.
fromAmountstring✅The amount in the source currency.
termsAcceptedboolean➖Identifies if the current terms and conditions are accepted.
📘

If dryRun = true is set, accepting the terms and conditions is optional. However, dryRun = false requires termsAccepted = true to function.

The latest version of Terms and Conditions can be retrieved by using Retrieve actual terms and conditions endpoint. The user should accept the following types of agreements:

  • payinTerms for Terms of Service;
  • payinPrivacyPolicy for Privacy Policy;
  • payinCookies for Cookies Policy.

The account parameter can be retrieved by using List all accounts endpoint.

Fee amount charged during the payin operation will be deducted from the amount specified in fromAmount field.

Request / response examples, dryRun = true:

Request Example

{
  "account": "954e1b53-7e72-4696-ba1f-f49f129da8e8",
  "fromAmount": 50.0,
  "fromCurrency": "USD",
  "termsAccepted": true,
  "toCurrency": "ETH"
}

Response Example

{
  "rateData": {
    "amount": 0.02006111,
    "currency": "ETH",
    "fee": {
      "ETH": "0.001194569546335588",
      "USD": "2.81"
    },
    "fiatAmount": 50.00,
    "fiatCurrency": "USD",
    "maxFiat": 937.65,
    "minFiat": 11.73,
    "rate": 2352.31,
    "reverseRate": 0.00042511,
    "subtotal": {
      "ETH": "0.020061116331521841",
      "USD": "47.19"
    },
    "total": {
      "ETH": "0.021255685877857429",
      "USD": "50.00"
    }
  },
  "validUntil": "2026-05-06T15:38:29.188+00:00"
}

Request / response examples, dryRun = false:

Request Example

{
  "account": "954e1b53-7e72-4696-ba1f-f49f129da8e8",
  "fromAmount": 50.0,
  "fromCurrency": "USD",
  "termsAccepted": true,
  "toCurrency": "ETH"
}

Response Example

{
  "redirectUrl": "https://platform-api.sandbox.testessential.net/front-gateway/mercuryo/redirect",
  "widgetUrl": "https://sandbox-exchange.mrcr.io?init_token=0fb5dd499597a9299&init_token_type=sdk_partner_authorization&widget_id=abe61aca-26e3-4848-b1f0-44e92eca6c03&type=buy&currency=ETH&fix_currency=true&fiat_amount=50.0&fix_fiat_amount=true&fiat_currency=USD&fix_fiat_currency=true&address=0x19a8A296C744f8FAb763aE2451A36AA8be5B5AdC&network=ETHEREUM&signature=v2:184a8d7e54acd9375bcfe0ceea56ebcabd636b2d841dc03d3f65da48b5abb28e88630080306779d388da3cff1cd9af3c0e93193b541f02cf18105e973b9615be&merchant_transaction_id=0cf9832d-1b78-4837-a273-e790d3b5d844&lang=en&redirect_url=https://platform-api.sandbox.testessential.net/front-gateway/mercuryo/redirect&payment_method=card"
}
📘

When calling the POST /wallet/direct-payin request, the system checks the user’s IP address against a list of restricted countries — the list can be provided by the Key Account Manager. If all checks pass, the response contains a widget URL. Otherwise, the operation is blocked and the following error is returned: Unfortunately, this feature isn’t available in your region due to legal or regulatory requirements.


Step 4. Redirect and checkout

Redirect the user with the widget URL provided in the previous step. There, the user can complete the payment.

📘

In the sandbox environment, use the following card details to achieve the expected payment outcome. Using any other card details may cause the feature to malfunction.

Card #1

  • Card Number: 4444 4444 4444 3333.
  • Expiration Date: any future date.
  • CVV: 123.
  • Cardholder Name: name + surname.

Card #2

  • Card Number: 5555 4444 3333 1111.
  • Expiration Date: any future date.
  • CVV: 123 for success, 555 for fail.
  • Cardholder Name: name + surname.

Once the payment is successful, the user will be automatically redirected to the URL specified in the redirectUrl parameter:

You can check the transaction result via the Get Crypto and IBAN Transactions History endpoint: the operationType field will indicate the transaction type as DIRECT_PAYIN.


Updated 7 days ago