On- and Off-Ramp Redirect Guide (1.6.0)

About

On- and Off-Ramp — integrated via Redirect — allows you to create a widget for buying and selling crypto currencies. Unverified users can buy crypto up to EUR 699.

In addition, the solution offers a feature with the ability of issuing a Mercuryo Spend virtual payment card for end-user. Once the Mercuryo Spend card is issued, it can be used when selling crypto for fiat money and withdrawing funds, as well as in POS and e-commerce transactions. Contact your integration manager to enable this feature. There can be only one opened Mercuryo Spend card per end-user. If the card is already opened, the end-user will see it in the list of cards.

Compatibility

Use Mercuryo wrappers for iOS and Android to add the widget to your mobile app.

Card Payments

Mercuryo accepts Mastercard and Visa.

Mobile Payment Services

Apple Pay

WebView Custom Tab
Safari Fully Compatible Incompatible
Google Chrome Incompatible Incompatible
Chromium Browsers Incompatible Incompatible

Google Pay

WebView Custom Tab
Safari Incompatible Fully Compatible
Google Chrome Incompatible Fully Compatible
Chromium Browsers Incompatible Fully Compatible

Note the list of countries where Google Pay is supported for payments on websites and apps. Also, keep in mind the list of countries where Mercuryo operates.

Testing

Start with the Sandbox environment to:

  • Walk through the scenarios.
  • Test endpoints.
  • Test the transaction operation.

To access the Sandbox environment, ask your integration manager to give you credentials and whitelist all your IP addresses for using with the Sandbox environment.

Testnets

Testnet Address Supported Cryptocurrency
BTC Testnet msBE6aCaAesegu4VzbQW3L5xWBL8vi15Q7 Bitcoin
ETH Sepolia 0xA14691F9f1F851bd0c20115Ec10B25FC174371DF Ethereum (ETH) and USDT

Sandbox URLs

  • Dashboard https://sandbox-dashboard.mrcr.io.
  • Widget https://sandbox-exchange.mrcr.io.
  • API Host https://sandbox-api.mrcr.io.

Sandbox Payment Card Details

  • Card Number 4444 4444 4444 3333.
  • Expiration Date any future date.
  • CVV 123.
  • Cardholder Name name + surname.
  • Enter hint in the additional window.

Widget Creation

To start using the On- and Off-Ramp widget, get dashboard credentials, sign in, and set up your widget. You will need the widget ID and signature parameters to enable buying and selling crypto.

To create a widget, go to Widgets > Add Widget.

In the Domain URL field, enter https://exchange.mercuryo.io (this URL is for production). Leave no symbols or backspaces after the https://exchange.mercuryo.io URL. The widget won’t work properly and you’ll see the widget.mercuryo.io refused to connect message.

Widget Parameters

The On- and Off-Ramp widget uses these URL parameters. These parameters can fill in up to 90% of the information and the user will have to enter only numbers.

Blockchain Wallet Signature

Use the signature parameter to protect your widget ID and parameters against the forgery. The signature parameter is always required. A signature is generated using this algorithm: signature = sha512(address+secret). There is no space between address and secret.

Steps:

  1. Go to Widgets and select your widget. Find Secret Key at the bottom.
  2. Paste the address and secret — addresssecret — into the SHA512 calculator to generate a signature.
  3. Append the signature to the widget URL.

Example:

The signature is verified before the 3-D Secure step. If the signature is invalid, the Signature is invalid message will be displayed. The user won't be able to complete the operation.

Integrating On-Ramps using Custom Tab on Android

Custom Tabs present effective solution for apps like yours, particularly when it comes to Google Pay integration. They are not just about aesthetics or user experience; they are mainly about functionality, specifically enabling Google Pay to work seamlessly within your app.

Here's a Kotlin code snippet to illustrate how you can launch our exchange URL, https://exchange.mercuryo.io, within a Custom Tab:

kotlinCopy codeval url = "https://exchange.mercuryo.io"
val intent = Builder().build()
intent.launchUrl(requireContext(), Uri.parse(url))

One advantage of using Custom Tabs is that the URL stays consistent with WebView integration. This helps to maintain a unified user experience, but more importantly, it ensures that critical functionalities like Google Pay work without any glitches.

Custom Tabs also offer some customization options, although they may not be the primary concern in this context. You can change the toolbar color, set custom enter and exit animations, and make other adjustments. For example:

kotlinCopy codeval customTabsIntent = CustomTabsIntent.Builder()
   .setToolbarColor(Color.BLUE)
   .build()
customTabsIntent.setStartAnimations(this, R.anim.slide_in_right, R.anim.slide_out_left)
customTabsIntent.setExitAnimations(this, R.anim.slide_in_left, R.anim.slide_out_right)

While Custom Tabs integration might feel like a necessary step rather than an optional enhancement, our data does indicate a positive outcome. Custom Tab integration can lead to higher conversion rates for mobile payment options. It's a way to ensure that the desired functionalities, especially Google Pay, are working correctly.

In conclusion, integrating Custom Tabs with our exchange URL is a practical move to ensure that Google Pay operates smoothly within your app. Though it may feel like a forced solution, it comes with benefits that align with the current trends in mobile commerce. Please contact your integration manager to discuss further how this integration can best serve your specific needs.

Callbacks

Mercuryo sends callbacks when the transaction status changes. Set up a callback URL to receive callbacks.

Steps

  1. Sign in the Dashboard.
  2. Go to Widgets.
  3. Select a widget.
  4. Fill in the field Callback URL.

Go to Widget Callbacks to browse callbacks, resend a callback, and send a test callback.

Callback Body

"data": {
            "id": "0c6466a43af411905",
            "type": "buy",
            "user": {
                "email": "user@mercuryo.io",
                "phone": "+3570000000",
                "uuid4": "d80e72e4-4d6d-4f4b-aaf5-44d9143d8558",
                "country_code": "cy"
            },
            "amount": "0.00046199",
            "status": "new",
            "network": "BITCOIN",
            "currency": "BTC",
            "created_at": "2024-07-31 07:47:59",
            "updated_at": "2024-07-31 07:47:59",
            "fiat_amount": "45.00",
            "created_at_ts": 1722412079,
            "fiat_currency": "USD",
            "updated_at_ts": 1722412079,
            "payment_method": "card",
            "card_masked_pan": null,
            "merchant_transaction_id": null
        }

Differentiate between sell operations made on Spend cards and those made on external cards through the callback:

  • Spend card opening:

    type: "sell"
    payment_method: "spend_card_open"
    
  • Spend card top-up:

    type: "sell"
    payment_method: "spend_card_topup"
    
  • Sell to external card:

    type: "sell"
    payment_method: "card"
    

Callback Signature

The sign key is used for checking the callback signature. When the transaction status changes, the merchant receives a request with transaction data from Mercuryo. If you use callbacks, you can set up the signature check.

You can check the signature by generating a hash with the HMAC sha256 algorithm and a key from the Sign Key field in the Dashboard. Check the X-Signature HTTP header against the generated hash.

The signature is generated using the whole callback body payload as an input. So, it's required to provide the whole callback body.

Transactions

Current section depicts supported transaction types and related statuses.

Buy

Buy with card option (including mobile pay)

This is the case when purchase is made with the card.

  1. new: a new transaction was created.
  2. pending: standing by for 3-D Secure verification.
  3. cancelled: a transaction was canceled usually due to the timeout.
  4. paid: the money deposited from a payment card.
  5. order_failed: a transaction was rejected by a bank.
  6. order_scheduled: the money is held on the card, standing by for the KYC verification; if the verification fails, the money will be returned.
  7. order_verified_not_complete: the verification is successful, an order was queued on an exchange.
  8. failed_exchange: Mercuryo failed to exchange for various reasons.

Buy with invoice option

This is the case when purchase is made with the invoice method.

  1. new: a new transaction was created.
  2. payment_received: Mercuryo received a callback that the money has been received through the buyer's bank.
  3. completed: the crypto transferred to the user address.
  4. refund_in_progress: waiting for money refund to the user.
  5. refunded: successful money refund to the user is made.
  6. failed: a transaction was rejected/failed. For example, in case when the user cancelled the payment themselves or abandoned the payment and did not pay, or if the bank rejected the transaction, or if there is an error creating an invoice on the Mercuryo side.
  7. order_failed: a transaction was rejected/failed in case if the user has a negative balance in the crypto wallet.
  8. cancelled: a transaction was canceled usually due to the timeout.

Withdraw

Withdraw usually follows the successful buy transaction, or in case of the failed sell transaction.

  1. new: a new transaction was created.
  2. pending: a transaction in progress.
  3. completed: the money transferred to the user address.
  4. failed: a transaction failed.

Sell

Standard sell without the option of opening a Spend card

  1. new: a new transaction was created.
  2. pending: a transaction in progress.
  3. succeeded: the money transferred to the card.
  4. failed: a transaction failed.

Fiat Card Sell with the option of opening a Spend card

Opening a Spend card is a feature with the ability of issuing a Mercuryo virtual payment card for end-user in order to use it when selling crypto for fiat money and withdrawing funds. Contact your integration manager to enable this feature.

The difference from the standard sell is that the fiat_card_sell transaction in the new status is created after a successful deposit. In the standard sell, the transaction is created before the deposit.

  1. new: a new transaction was created.
  2. pending: a transaction in progress.
  3. succeeded: the money transferred to the card.
  4. failed: a transaction failed.

Deposit

Deposit follows the standard successful sell transaction, or goes before the fiat_card_sell transaction.

  1. new: a new transaction was created.
  2. pending: a transaction in progress.
  3. completed: the money transferred to Mercuryo.
  4. failed: a transaction failed.

KYC

Know Your Customer (KYC) procedures are indispensable for financial institutions to verify their clients and keep business on the safe side.

KYC procedures help Mercuryo fight financial crime. Therefore, it prevents mixing your users’ funds with illegal funds of bad actors and perpetrators of any sort. Identity verification is a legal obligation to be compliant with AML/CFT laws. Mercuryo is strongly committed to the highest industry standards of clients' security, which requires protecting the integrity of the entire financial system.

SumSub is the major KYC procedure provider of Mercuryo.

Verification includes the following:

  • Identity verification (passport, ID card or driving license).
  • Liveness test.

For Mercuryo Spend card feature, the list of required documents depends on the end-user's country of citizenship:

  • European Economic Area (EEA), European Union (EU), United Kingdom (UK)*:
    • Passport with citizenship or ID card with citizenship.
    • Manual input of user address.
    • Liveness test (selfie).
  • Switzerland and other countries where Mercuryo Off-ramp operations are allowed:
    • Passport with citizenship or ID card with citizenship.
    • Residence permit (accepted from EU countries only).
    • Proof of address (accepted from EU countries only).
    • Liveness test (selfie).

*- ID card is not accepted for UK citizens.

Identity Verification

The document must have:

  • Full name.
  • MRZ code.
  • Citizenship.
  • Date of birth.
  • Document number.
  • Issuing authority.
  • Date of issue.

Meet these requirements:

  • The document must be unexpired.
  • The document must be scanned or photographed.
  • All the corners and sides of the document must be visible.
  • All the information must be clear and readable.

Integration

There are two cases for integrating KYC procedures depending on your user onboarding:

  1. If you don’t implement any KYC procedures.
  2. If you implement SumSub KYC procedures.

Contact your account manager if you have any questions regarding KYC procedures.

Standard

If you don’t implement any KYC procedures, we provide the SumSub interface to do KYC verification directly in Mercuryo.

There is a standard flow when a user does the KYC procedures directly in the widget. See the identity verification requirements above.

SumSub Share Token

If you have already integrated SumSub KYC procedures, you can share your SumSub applicants with Mercuryo using the share token. The SumSub share token is used by Mercuryo to share applicants and complete the KYC procedures. So, the users won’t have to do the verification twice. See how it works.

Make sure that your applicant’s documents are up-to-date before sharing an applicant using the share token. Mercuryo can accept the share token only once due to the SumSub architecture. The Sandbox environment requires approving users manually.

Steps

  1. Use https://api.sumsub.com/resources/accessTokens/-/shareToken to generate the share_token parameter value.
  2. The applicantId and forClientId=Mercuryo parameters are required. Enter the generated value in the widget URL.
    1. Example: https://exchange.mercuryo.io/?share_token=[value].

Silent Authentication

The silent authentication is a tool that makes signing in Mercuryo easier for users.

The silent authentication allows for skipping the authentication in the widget: just pass the token in the URL, so that the user doesn't have to enter credentials.

You have to ask the user to agree to the Terms of Service on your front end to share the user data with Mercuryo.

You have to allow Mercuryo to use the user data for the registration and with third parties.

There are two cases of the silent authentication depending on your user onboarding:

  1. If you don’t implement any KYC procedures: Silent Sign-Up.
  2. If you implement SumSub KYC procedures: Silent Sign-Up + SumSub KYC.

Silent Sign-Up

For users without a Mercuryo account.

The Sdk-Partner-Token header is required. Contact your integration manager to get the header.

Required parameters for POST /sdk-partner/sign-up:

  1. email.
  2. accept.

Steps

  1. Use POST /sdk-partner/sign-up to get init_token and init_token_type.
    1. init_token expires after the first time it was passed or after one hour.
  2. Pass the init_token and init_token_type parameters in the URL.
  3. Redirect the user to the widget.
    1. Redirect example: https://exchange.mercuryo.io/?init_token_type=sdk_partner_authorization&init_token=0a25dd714163a9006.

Silent Sign-Up + SumSub KYC

Sign up verified users and share them with Mercuryo using SumSub share token.

The Sdk-Partner-Token header is required. Contact your integration manager to get the header.

Required parameters for POST /sdk-partner/sign-up:

  1. email.
  2. accept.
  3. share_token.

Steps

  1. Use POST /sdk-partner/sign-up to get init_token and init_token_type.
    1. init_token expires after the first time it was passed or after one hour.
  2. Pass the init_token and init_token_type parameters in the URL.
  3. Redirect the user to the widget.
    1. Redirect example: https://exchange.mercuryo.io/?init_token_type=sdk_partner_authorization&init_token=0a25dd714163a9006&share_token=_act-jwt-eyJhbGciOiJub25lIn0.eyJqdGkiOiJfYWN0LWYwOTBmZWEyLTUxMDItNDkxYy1hZGM4LThmZjg5YmRhNjY0YyIsInVybCI6Imh0dHBzOi8vYXBpLnN1bXN1Yi5jb20ifQ.

Silent Sign-In

For already registered users.

The Sdk-Partner-Token header is required. Contact your integration manager to get the header.

Steps

  1. Use POST /sdk-partner/login to get init_token and init_token_type.
    1. init_token expires after the first time it was passed or after one hour.
  2. Pass the init_token and init_token_type parameters in the URL.
  3. Redirect the user to the widget.
    1. Redirect example: https://exchange.mercuryo.io/?init_token_type=sdk_partner_authorization&init_token=0a25dd714163a9006.

On-Ramp. Crypto Purchase.

Buying crypto with fiat money using a payment card.

Steps

  1. Use GET /lib/currencies to get available currencies.
  2. Use GET /public/card-countries to get available countries.
  3. Use GET /public/data-by-ip to check user's location.
  4. Use GET /public/currency-limits to get user limits.
  5. Use GET /widget/buy/rate to see the transaction total.
  6. Use GET /sdk-partner/transactions to get the transaction status.
  7. Redirect the user to your widget. Also, you can preselect parameters from this table.
    1. Example: the user buys USDT with EUR 200. The URL is https://exchange.mercuryo.io/?fiat_currency=EUR&currency=USDT&fiat_amount=200.

Off-Ramp. Crypto Sell.

Selling crypto for fiat money and withdrawing funds to a payment card.

The user must be signed in and verified (valid KYC). Mercuryo won’t complete the transaction if the verification is expired.

If the crypto is not received within 6 hours, the sell request will fail. If the crypto is received after this period, it will be credited to the user's wallet balance as a regular deposit (in the crypto itself, without converting to fiat). The crypto will only be refunded to the refund_address if there is an error in the sell process on the Mercuryo side.

Selling crypto is disabled for a newly created widget. Contact your integration manager to enable this feature.

EUR and USD are the only available currencies for selling crypto.

Steps

  1. Use GET /lib/currencies to get available crypto currencies.
  2. Use GET /public/card-countries to get available countries.
  3. Use GET /public/data-by-ip to check user's location.
  4. Use GET /public/currency-limits to get user limits.
  5. Use GET /widget/sell/rate to see the transaction total.
  6. Use GET /sdk-partner/transactions to get the transaction status.
  7. Redirect the user to your widget. Also, you can preselect parameters from this table.
    1. Example: the user sells USDT 200 for EUR. The URL is https://exchange.mercuryo.io/?fiat_currency=EUR&currency=USDT&amount=200&type=sell.

Recurring Payment

Simplifies the process of managing and making regular payments at regular intervals, such as monthly or annually. Allows users to set up automatic payments for recurring bills or subscriptions using their credit or debit cards.

Parameters

The following widget parameters are used to choose and configure the flow of recurring payments.

Parameter Parameter Value Description
widget_flow CONST recurrent Mandatory. Enables the recurring payment flow
partner_flow Applicable to the partners having a customized UI
address {crypto_address} Destination address
currency {crypto_currency} Cryptocurrency
fix_network {crypto_network} Example: ETHEREUM, BINANCESMARTCHAIN or TRON
fiat_currency {fiat_currency} Fiat currency
redirect_url {redirect_url} URL where to return the user after creating a recurring purchase subscription
frequency enum[weekly, monthly] If this value is set, the frequency will be fixed in OOR widget's UI. To change it, the user will have to go back to the partner’s screen
charge_day enum[1, 2, 3, …, 31] for frequency:monthly; enum[monday, tuesday, …, sunday] for frequency:weekly If this value is set, it will be fixed in OOR widget's UI. To change it, the user will have to go back to the partner’s screen

URL example: https://exchange.mercuryo.io/?widget_id=6b5ab199-cdb8-4426-8a34-3ff9d24188cf&widget_flow=recurrent&fiat_currency=EUR&currency=USDT&network=TRON&fiat_amount=540&address=TQhoZ9hgkQ1NMAMJZ23EPaGtJDMCmv6yJd

Mercuryo Spend Card

A feature with the ability of issuing a Mercuryo Spend virtual payment card for end-user. Contact your integration manager to enable this feature.

Mercuryo Spend card can be opened during the Off-ramp process. The end-user must be signed in, successfully complete KYC procedures (valid KYC), and have a valid mobile phone number to issue a Mercuryo Spend virtual payment card. There can be only one card per end-user. If the card is already opened, the end-user will see it in the list of cards.

If you want users to immediately be redirected to the Spend card opening flow, specify the following parameters in your widget:

  1. Turn on sell flow: as the type parameter, specify sell.
  2. Specify EUR in the fiat_currency parameter.
  3. Add the payment_method parameter with the spend_card value.

URL example: https://exchange.mercuryo.io/?type=sell&fiat_currency=EUR&fix_fiat_currency=true&fix_payment_method=true&payment_method=spend_card

End-user Flow for Issuing New Mercuryo Spend Card

  1. User specifies the amount for Sell operation (crypto for fiat money).
  2. As the payment method, an option to issue a Mercuryo Spend card is chosen in order to withdraw funds there. This option is available, if the feature is enabled by integration manager.
  3. User passes through the KYC verification procedure, if needed.
  4. For 3-D Secure transaction confirmation, user provides the phone number and enters the code sent to it.
  5. User confirms the transaction and performs transfer.
  6. After blockchain transaction is successfully completed, the notification of successful transfer is sent to user.
  7. Mercuryo issues the card after receiving crypto.
  8. Card details are displayed to the user once the card is loaded and ready.

Once the card is issued, it can be used when selling crypto for fiat money and withdrawing funds, as well as in POS and e-commerce transactions.

Mercuryo PRO

Mercuryo PRO is an OTC widget for businesses and individuals intending to make a transaction of 50.000 EUR/USD or more via IBAN transfer. Mercuryo PRO offers high-volume transaction processing with personalized support from a dedicated Customer Success Manager, all without leaving the Mercuryo interface.

Conditions and Details

  1. The initial purchase/sale transaction starts from the equivalent of 50.000 EUR and continues indefinitely, but within the framework of banking regulations.
  2. For each transaction, a Customer Success Manager is assigned who guides the client from the beginning to the end of the transaction.
  3. The commission is lower: starts from 1% and can be less for amounts from 1 million EUR.
  4. Only USD/EUR are available at the moment.
  5. KYB/KYC procedures differ from the basic verification in a regular On- and Off-Ramp widget.
  6. An agreement is concluded between Mercuryo and the client.

Parameters Used

Parameter Name Description Example
otc_id Transaction ID to assign 123
fiat_amount Sets an amount of fiat currency 50000
fiat_currency Sets fiat currency EUR
type Type of operation buy or sell
amount Sets an amount of cryptocurrency 0.1
currency Sets cryptocurrency BTC
network Sets network SOLANA

Example of the widget's URL: https://exchange.mercuryo.io/?otc_id=123&fiat_amount=60000&fiat_currency=EUR&type=sell&currency=USDC&network=POLYGON

Try Again Feature

The feature allows users to quickly retry a payment after a failed transaction.

The Try Again feature has several customizations. Please contact your integration manager to adjust the settings following your preferences.

Retry Scenarios Configuration

You can customize the retry scenarios by enabling or disabling the following options:

  • Change Transaction Amount: Allow or restrict users from modifying the transaction amount during retries.
  • Change Payment Method: Enable or disable the option for users to switch payment methods when retrying a transaction.

Callbacks

Enabling the Try Again feature affects callbacks. Please make sure that your back-end is ready for changes.

There are a few parameters in the callback payload that may change when the Try Again feature is enabled:

Parameter Description
id Mercuryo’s transaction ID. It changes when a user creates a new transaction while the merchant_transaction_id does not change
created_at Mercuryo creates a new transaction. The new transaction gets a new creation date value
created_at_ts Mercuryo creates a new transaction. The new transaction gets a new creation date value
fiat_currency It might change if Change Transaction Amount settings are enabled
fiat_amount It might change if Change Transaction Amount settings are enabled
amount It might change if Change Transaction Amount settings are enabled
rate It might change if Change Transaction Amount settings are enabled
payment_method It might change if Change Payment Method settings are enabled

Example of changing callbacks payload

First transaction’s callback example:

{
  "url": "",
  "sign_key": "*****",
  "widget_id": "d8f5099f-cbb7-1f9f-a34b-256c23f12345",
  "payload": {
    "eventId": "ead92193-5310-4962-9730-d7280d623410",
    "data": {
      "id": "0c9be256a0eed7062",
      "merchant_transaction_id": "trx_20240911_102155662",
      "created_at": "2024-09-11 09:48:51",
      "updated_at": "2024-09-11 09:48:53",
      "type": "buy",
      "currency": "BTC",
      "amount": "0.00048148",
      "fiat_currency": "EUR",
      "fiat_amount": "25.00",
      "status": "order_scheduled",
      "created_at_ts": 1726048131,
      "updated_at_ts": 1726048133,
      "user": {
        "uuid4": "00e0043f-9c9a-4a93-b4b3-f10729af6ef6",
        "country_code": "de",
        "phone": "*****",
        "email": "*****"
      },
      "network": "BITCOIN",
      "card": {
        "number": "*****"
      },
      "fee": "0.28",
      "partner_fee": "0.00",
      "rate": "51341.70",
      "payment_method": "card"
    }
  }
}

Second transaction’s callback example:

{
  "url": "",
  "sign_key": "*****",
  "widget_id": "d8f5099f-cbb7-1f9f-a34b-256c23f12345",
  "payload": {
    "eventId": "ead92193-5310-4962-9730-d7280d623410",
    "data": {
      "id": "0c9be512a0ebd8012",
      "merchant_transaction_id": "trx_20240911_102155662",
      "created_at": "2024-09-11 09:50:03",
      "updated_at": "2024-09-11 09:50:53",
      "type": "buy",
      "currency": "BTC",
      "amount": "0.00024148",
      "fiat_currency": "USD",
      "fiat_amount": "13.7",
      "status": "paid",
      "created_at_ts": 1726056363,
      "updated_at_ts": 1726056363,
      "user": {
        "uuid4": "00e0043f-9c9a-4a93-b4b3-f10729af6ef6",
        "country_code": "de",
        "phone": "*****",
        "email": "*****"
      },
      "network": "BITCOIN",
      "fee": "0.15",
      "partner_fee": "0.00",
      "rate": "56341.70",
      "payment_method": "mobile_pay"
    }
  }
}

Callback Scenarios

The Try Again feature also includes advanced settings for managing callback notifications sent to your system.

Disable All Non-final Callbacks

If enabled, Mercuryo will only send callbacks with final statuses, such as paid, cancelled or order_failed. Intermediate statuses such as new and pending will not trigger callbacks.

Important: If you do not disable intermediate callbacks, your system will receive multiple callbacks, which may create confusion, or overload your system, especially when multiple transactions are created by a user in rapid succession.

Example:

  • The user creates multiple transactions. If intermediate callbacks are enabled, your system will receive a sequence such as: "new" → "pending" → "new" → "pending" → "new" → "pending" → "{final_status}" (based on the result of the transaction).

Disable Intermediate Callbacks for following transactions

If enabled, Mercuryo will not send intermediate callbacks (such as new, cancelled or pending) for any transaction after the first one in a series of retries.

For the first transaction, intermediate callbacks will still be sent.

Customization

To customize the Mercuryo Widget, follow these instructions in Figma.

Customize the appearance: put a theme name at the end of this URL https://exchange.mercuryo.io/?theme=THEME_NAME.

Themes

  1. exmo
  2. bitx
  3. btc_alpha
  4. xzen
  5. ch
  6. savl
  7. spatium
  8. now_payments
  9. invity
  10. phemex
  11. lumi
  12. trustwallet
  13. roobee
  14. kickex
  15. quantfury
  16. simpleswap
  17. 1inch
  18. digifinex
  19. mycelium
  20. coinstats
  21. advantechLight
  22. advantechDark
  23. swapspace
  24. tonkeeper
  25. bitpapa
  26. bitpapaDark
  27. czixlight
  28. czixdark
  29. swapspace2
  30. 3commas_light
  31. 3commas_dark
  32. 3commas_web_dark
  33. 3commas_web_light
  34. unionbtc arctic
  35. dark_ch
  36. light_ch
  37. white_market
  38. exolix
  39. grapherex_light
  40. grapherex_dark
  41. haru_light
  42. haru_dark

To get Mercuryo fonts, download this archive.

To get Mercuryo logos, download this archive.

FAQ

Visit Help Center

Where does Mercuryo operate?

Mercuryo is operational and allows end-users from all countries, except for the following list. The below details are used to identify whether end-user’s country is from non-operational list:

  1. End-user's IP address.
  2. End-user’s card issuer country.
  3. Documents provided for passing KYC procedure which verify end-user’s country of residence.

Note that the Off-Ramp operations are available in selected countries for external non-Mercuryo cards (Visa and Master).

Mercuryo Spend card can be opened for citizens/nationals from the following countries: European Economic Area (EEA), European Union (EU), Switzerland, United Kingdom (UK), and other countries where Mercuryo Off-ramp operations are allowed.

Helper

/lib/currencies

Get supported currencies

Responses
200

OK

403

Forbidden

500

Internal server error

get/lib/currencies
Response samples
application/json
{}

/public/card-countries

Get countries with card payment available

Responses
200

OK

403

Forbidden

500

Internal server error

get/public/card-countries
Response samples
application/json
{
  • "data": [
    ],
  • "status": "200"
}

Limits by currencies

Parse widget limits from antifraud and map it

Request
query Parameters
widget_id
required
string

Widget ID

from
required
string

Currency from

to
required
string

Currency to

type
string

Direction type

is_total
boolean

Is total

amount
number

Amount

Responses
200

OK

get/public/currency-limits
Response samples
application/json
{
  • "code": 0,
  • "data": {
    },
  • "message": "string",
  • "status": 0
}

Get geo data for IP

Get geo data for IP

Request
query Parameters
ip
required
string

IP address

Responses
200

OK

get/public/data-by-ip
Response samples
application/json
{
  • "data": {
    },
  • "status": 0
}

Get rates endpoint

Get rates endpoint

Request
query Parameters
widget_id
required
string

Widget ID

use_partner_fee
boolean

Use partner fee

use_fee
boolean

Use fee

flatten_result
boolean

Flatten result

is_amount_without_fee
boolean

Is Amount Without Fee

network
required
string

Network layer-2

Responses
200

OK

get/public/rates
Response samples
application/json
{
  • "data": {
    },
  • "status": 0
}

/transactions

Transactions for sdk partners

Securitysdk-partner-token
Request
query Parameters
merchant_transaction_id
string

Merchant transaction id

date_start
string

Unix Timestamp search from

date_end
string

Unix Timestamp search end

status
string

Transaction status

show_retries
boolean

Show retries transactions

limit
string
Default: "50"

Limit of rows max 50, min 5

offset
string

Type of client

Responses
200

Get transactions

401

401000: Authorization failed

403

Error codes:
* 403007: Transaction lock error. Please contact support;
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

500

500001: Various reasons, check the message field

get/sdk-partner/transactions
Response samples
application/json
{
  • "data": [
    ],
  • "next": "string",
  • "prev": "string",
  • "status": "200",
  • "total": "100"
}

Sell

/public/convert

Get off-ramp conversion rates

Request
query Parameters
from
required
string

Currency to convert from

to
required
string

Currency to convert to

type
required
string

Conversion type (buy/sell)

amount
required
string

Amount to convert

widget_id
required
string

Widget id

is_total
boolean
Default: "true"

Is passed amount with fee

payment_method
string

Payment method. Available: card, volt, apple, google

address
string

User wallet address. Available only if feature enabled for widget

ip_address
string

User IP address. Feature must be enabled for widget.

card_type
string

Card payment system. Feature must be enabled for widget. Note that parameter can be used only with ip_address

country
string

User country. Feature must be enabled for widget. Note that ip_address takes precedence over country

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400005: Amount off limits

403

Forbidden

500

Internal server error

get/public/convert
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/public/currencies-sell

Get fiat and crypto currencies available for sell operation

Responses
200

OK

403

Forbidden

500

Internal server error

get/public/currencies-sell
Response samples
application/json
{
  • "data": [
    ],
  • "status": "200"
}

/widget/sell/rate

Get currency sell rate

Request
query Parameters
from
required
string

Currency to convert from

to
required
string

Currency to convert to

type
required
string

Transactions type

amount
required
string

Amount to convert

is_total
boolean
Default: "true"

Is passed amount with fee

widget_id
required
string

Widget id

network
string

Cryptocurrency network

payment_method
string
Default: "card"

Payment method for fees and kyc

Enum: "card" "fiat_card_open" "fiat_card_topup" "sepa"
Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400005: Amount off limits

403

Forbidden

500

Internal server error

get/widget/sell/rate
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

Buy

/public/currencies-buy

Get fiat and crypto currencies available for buy operation

Responses
200

OK

403

Forbidden

500

Internal server error

get/public/currencies-buy
Response samples
application/json
{
  • "data": [
    ],
  • "status": "200"
}

/widget/buy/rate

Get currency rate

Request
query Parameters
from
required
string

Currency to convert from

to
required
string

Currency to convert to

type
required
string

Transactions type

amount
required
string

Amount to convert

is_total
boolean
Default: "true"

Is passed amount with fee

widget_id
required
string

Widget id

network
string

Cryptocurrency network

payment_method
string

Payment method. Available: card, volt, apple, google, pix, invoice.

address
string

User wallet address. Available only if feature enabled for widget

card_bin
string

User card bin

card_id
string

Mercuryo card id

ip_address
string

User IP address. Feature must be enabled for widget.

card_type
string

Card payment system. Feature must be enabled for widget. Note that parameter can be used only with ip_address

country
string

User country. Feature must be enabled for widget. Note that ip_address takes precedence over country

method_code
string

Payment method code for invoice payment. Applies when the value of payment_method = invoice. Available values: EightBWorld_bri, EightBWorld_bni, EightBWorld_qris , EightBWorld_ovo

merchant_transaction_id
string

Id, which is issued by the merchant at the beginning of interaction with the user

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400005: Amount off limits

403

Forbidden

500

Internal server error

get/widget/buy/rate
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/widget/mobile-pay/rate

Get currency rate

Request
query Parameters
from
required
string

Currency to convert from

to
required
string

Currency to convert to

type
required
string

Transactions type

amount
required
string

Amount to convert

is_total
boolean
Default: "true"

Is passed amount with fee

widget_id
required
string

Widget id

network
string

Cryptocurrency network

payment_method
required
string

Mobile payment method

Enum: "Apple" "Google"
address
string

User wallet address. Available only if feature enabled for widget

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400005: Amount off limits

401

Can't get rates data

403

Forbidden

500

Internal server error

get/widget/mobile-pay/rate
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

User

/login

Login user

Securitysdk-partner-token
Request
Request Body schema: application/json
required

JSON Body

email
string

SDK user's email. Field is required unless phone or user_uuid4 is provided

phone
string

SDK user's phone number. Field is required unless phone or user_uuid4 is provided

user_uuid4
string

SDK user's uuid. Field is required unless email or phone is provided

Responses
200

OK

401

401000: Authorization failed

403

Error codes:
* 403007: Transaction lock error. Please contact support;
* 403020: IP is blacklisted;
* 403031: Login failed. Check the message field;

404

User is not found

405

405000: Method Not Allowed

500

Internal server error

post/sdk-partner/login
Request samples
application/json
{
  • "email": "someemail@gmail.com",
  • "phone": "+1234567890",
  • "user_uuid4": "ea159262-3aec-42e8-9cda-f2e5dcba576a"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/sign-up

Sign-up user

Securitysdk-partner-token
Request
Request Body schema: application/json
required

JSON Body

accept
required
boolean

accept

email
string

SDK user's email. Field isrequired unless phone is provided

language_code
string

ISO 639-1 standard language codes, defaults to en-US

share_token
string

SumSub share token

Responses
200

OK

401

401000: Authorization failed

403

Error codes:
* 403007: Transaction lock error. Please contact support;
* 403020: IP is blacklisted;
* 403031: Sign-up failed. Check the message field;

405

405000: Method Not Allowed

500

Internal server error

post/sdk-partner/sign-up
Request samples
application/json
{
  • "accept": "true",
  • "email": "someemail@gmail.com",
  • "language_code": "en-US",
  • "share_token": "_act-sbx-16a1bb3a-a43a-40ec-97fb-1771e487b5c2"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}