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.

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

Google Pay

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.

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

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.

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.

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.

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:

• Widget URL: https://exchange.mercuryo.io/?widget_id=0afcf059-392a-4a13-adeb-11f3ef3142ab&address=1FCraX5VzxNJGRzGxdzky33Fvmgt2x6Ymp&hide_address=true&signature=fe1380b023d1b3a0a0135c048eb65a9ba8bd028e7a081e36fcdee0aae3fa91eb32081529034388b6dff70ab03cff84588695c2718eb522e06929d28b6e40625a.
• widget_id: widget ID.
• address: blockchain wallet address.
• hide_address: toggle hide address.
• signature: generated signature.

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.

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.

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":"0ab3f70c72c0f5056",
      "fee":"11.80",
      "card":{
         "number":"1111"
      },
      "rate":"25756.99",
      "type":"buy",
      "user":{
         "email":"sf@mercuryo.io",
         "phone":"+3570000000",
         "uuid4":"b5086805-4b83-4415-8a00-5c1ad43210b6",
         "country_code":"de"
      },
      "amount":"0.00148310",
      "status":"paid",
      "currency":"BTC",
      "created_at":"2023-09-07 07:32:33",
      "updated_at":"2023-09-07 07:32:46",
      "fiat_amount":"50.00",
      "partner_fee":"0.00",
      "created_at_ts":1694071953,
      "fiat_currency":"USD",
      "updated_at_ts":1694071966,
      "payment_method":"card",
      "card_masked_pan":null,
      "merchant_transaction_id":"123"
   }
}

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.

1. new: a new transaction was created.
2. pending: standing by for 3-D Secure or descriptor 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.
9. descriptor_failed: the user entered an invalid descriptor three times.

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.

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

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.

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.

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.

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.

Find out more about the requirements for the US and Russia.

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 country:

• Austria, Belgium, Bulgaria, Croatia, Republic of Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Iceland, Liechtenstein, Norway:
  • Passport with citizenship or ID card with citizenship.
  • Manual input of user address.
  • Liveness test (selfie).
• United Kingdom, Switzerland + all countries which are not in the blacklist:
  • 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).

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.

There are three 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.

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.

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].

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.

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.

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.

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.

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.

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.

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.

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. Currently, Mercuryo Spend card option is only available for EUR as currency for selling crypto. 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.

End-user Flow for Issuing New Mercuryo Spend Card

1. User selects Sell operation (crypto for fiat money) and specifies the amount.
2. While specifying the payment method, user chooses an option to issue a Mercuryo payment card in order to withdraw funds there. This option is available, if the feature is enabled by integration manager, and EUR is chosen for selling crypto.
3. User passes through the KYC verification procedure.
4. Mercuryo requires the user phone number. It will be used for 3-D Secure transaction confirmations.
5. User provides the phone number and enters the code sent to it.
6. User confirms the transaction and performs transfer.
7. After blockchain transaction is successfully completed, the notification of successful transfer is sent to user.
8. Mercuryo issues the card after receiving crypto.
9. 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 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

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

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.

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 end-users from the countries listed below:

• Austria, Belgium, Bulgaria, Croatia, Republic of Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden.
• United Kingdom, Switzerland, Iceland, Liechtenstein and Norway + all countries which are not in the blacklist.
  • Countries in the blacklist: Abkhazia, Afghanistan, Aland Islands, Algeria, American Samoa, Anguilla, Angola, Antarctica,Antigua and Barbuda, Bahamas, Barbados, Bangladesh, Belize, Bolivia, Burkina Faso, Burma, Burundi, Cambodia, Cayman Islands, Central African Republic, Chad, Chile, China, Cocos (Keeling) Island, Colombia, Comoros, Costa Rica, Cote d'Ivoire, Cuba, Democratic People's republic of Korea, Democratic Republic of the Congo, Djibouti, Ecuador, Equatorial Guinea, Eritrea, Ethiopia, Fiji, French Guiana, French Polynesia, Gabon, Gambia, Guam, Guatemala, Guernsey, Guinea, Guinea-Bissau, Haiti, Heard Island and McDonald Islands, Holy See, Honduras, Iraq, Islamic Republic of Iran, Isle of Man, Jamaica, Jordan, Kenya, Kosovo, Kuwait, Kyrgyzstan, Laos, Lesotho, Leban, Liberia, Libya, Macedonia, Malawi, Mali, Mauritania, Morocco, Mozambique, Namibia, Nepal, Nicaragua, Niger, Nigeria, Northern Mariana Islands, Occupied Palestinian Territory, Pakistan, Palau, Panama, Papua New Guinea, Peru, Puerto Rico, Republic of the Congo, Rwanda, Saint Barthelemy, Samoa, Saudi Arabia, Senegal, Seychelles, Sierra Leone, Somalia, South Ossetia, Sri Lanka, South Sudan, Sudan, Swaziland, Syrian Arab Republic, Tajikistan, Tanzania, Togo, Trinidad and Tobago, Tunisia, Turks and Caicos Islands, Uganda, United States, Vanuatu, Venezuela, Virgin Islands British, Virgin Islands US, Western Sahara, Yemen, Zambia, Zimbabwe.