Iframe OOR

About

Add crypto on-ramps and off-ramps. Let your users buy and sell cryptocurrency with fiat currency using our compliant, conversion-optimized widget.

What You Can Build

✅ Buy crypto with fiat – Credit card, debit card, Apple Pay, Google Pay and popular APMs

✅ Sell crypto for fiat – Direct to debit or credit card

✅ High conversions – Support 50+ cryptocurrencies and 40+ fiat currencies

✅ Built-in compliance – KYC/AML handled, €699 limit for light-KYC users

✅ Spend card – Issue virtual debit cards – 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 for more details, or email us at sales@mercuryo.io.

Integration Types

There are two types of integration available for the Mercuryo Widget:

  • iFrame Integration — the widget is embedded directly into your application using an iFrame.
  • Redirect Integration — users are redirected to the Mercuryo widget page. For more information, see the Redirect OOR tab.

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.

Supported Assets

Mercuryo supports a wide range of cryptocurrencies and tokens for purchase, sale, and transfer through our APIs and platform.

For the always up-to-date list of supported assets, please refer to:
Which cryptocurrencies are supported?

This list includes asset names, tickers, and network information, and is frequently updated.

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 0xbBC8f6B710359dbcdF02f9eb50Ade391890A6021 Ethereum (ETH) and USDT

Sandbox URLs

Sandbox Payment Card Details

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.

Production URLs:

Widget Creation

To start using the On- and Off-Ramp widget, get dashboard credentials, sign in, and set up your widget.

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

Steps

  1. Enter <div id="mercuryo-widget"></div> in <body></body>.
  2. For production environment, enter <script src="https://widget.mercuryo.io/embed.2.0.js"></script> at the end before </body>.
  3. For sandbox environment, enter <script src="https://sandbox-widget.mrcr.io/embed.2.0.js"></script> at the end before </body>.
  4. Call mercuryoWidget.run({ widgetId: 'a8c1dead-ed5f-4740-b9ce-c4ea7721c93b', host: document.getElementById('mercuryo-widget') });.
    1. widgetId, host, address, signature, merchant_transaction_id are required parameters.
  5. Use these widget parameters.
    1. Important: When integrating the widget via iFrame, make sure to enable camera permissions in your iFrame code. This is required for users to access the camera during the KYC liveness test.

Enter your domain in the Domain URL field. Leave no symbols or backspaces after the URL. The widget won't work properly and you'll see the widget.mercuryo.io refused to connect message.

Blockchain Wallet Signature

To strengthen security standards, we've introduced the version 2 of the signature mechanism.

The v2 signature requires additional parameters to ensure enhanced security:

  1. IP address of the user who opens the widget.
  2. merchantTransactionId parameter.

Signature Format

The v2 signature string is formed by concatenating the following values without spaces: addresssecretIpMerchanttransactionid,

where:

  • address: blockchain wallet address.
  • secret: your widget's secret key.
  • Ip: IP address of the user.
  • Merchanttransactionid: your merchant transaction ID.

Steps:

  1. Go to Widgets and select your widget.
  2. Find Secret at the bottom.
  3. Form the signature string by concatenating: addresssecretIpMerchanttransactionid.
  4. Paste the concatenated string into the SHA512 calculator to generate a signature.
  5. Add the v2: prefix to the generated signature.
  6. Append the signature to the widget URL.

Example: 

mercuryoWidget.run({
  widgetId: '0afcf059-392a-4a13-adeb-11f3ef3142ab',
  host: document.getElementById('mercuryo-widget'),
  address: '1FCraX5VzxNJGRzGxdzky33Fvmgt2x6Ymp',
  merchantTransactionId: '12345',
  signature: 'v2:9182a23f3cb7704f9e5a02c70c9d88bfecec799bdca191f39ed5eb8d22ca8d398cfa4d3a46109e523fb946bc25d24f77a8a2e54aaa6d6c819c7bcd98787b8015'
});

The v2 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 Callback URL field.

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
        }

In callbacks, transactions are identified by a combination of type and payment_method fields Differentiate between operations made on Spend cards and those made on external cards through the callback:

  • Spend card opening in Off-ramp scenario:

    type: "sell"
payment_method: "spend_card_open"

  • Spend card opening in On-ramp scenario:

    type: "buy"
payment_method: "spend"

  • Spend card top-up:

    type: "sell"
payment_method: "spend_card_topup"

    type: "fiat_deposit"
payment_method: "spend_card_topup"

  • Sell to external card:

    type: "sell"
payment_method: "card"

  • Buy to external card:

    type: "buy"
payment_method: "card"

Spend Card Events

Mercuryo sends callbacks for Spend card events:

  • When the card status changes.
  • When the card is replenished with crypto.
  • For the card transactions.

To set up a callback URL to receive callbacks for Spend card events, contact your integration manager.

Callback Body: Spend Card Status Change 

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8", // unique event identifier, the same for all retries of the same event
  "event_name": "card_status", 
  "card_id": "0c379cbae24f62922", 
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66", 
  }
  "status": "active", 
  "created_at": "2024-06-27 08:26:35", 
  "updated_at": "2024-06-27 08:26:41", 
}

If the callback service returns a 500 error, the system will retry the request using exponential backoff, up to a maximum of 10 attempts.

Callback Body: Replenishing Spend Card with Crypto 

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "crypto_top_up",
  "card_id": "0c379cbae24f62922", 
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66" 
  },
  "sell_request": {
    "id": "0daa380ba39596745", 
    "merchant_transaction_id": "00357ec76de855485", 
    "status": "new|pending|succeeded|failed", 
    "fiat_amount": "130.34", 
    "fiat_currency": "EUR", 
    "fee": "2",  
    "crypto_amount": "0.02", 
    "crypto_currency": "BTC" 
  },
  "refund_address": "0xc83935B7295FEC64E32B62C33C24dFdfE04092A9", 
  "address": "0xc83935B7295FEC64E32B62C33C24dFdfE04092A9", 
  "sender_address": ["0xc83935B7295FEC64E32B62C33C24dFdfE04092A9"], 
  "card_balance": "130|null", 
  "created_at": "2024-06-27 08:26:35", 
  "updated_at": "2024-06-27 08:26:41" 
}

Callback Body: Spend Card Transactions 

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "card_transaction",
  "card_id": "0c379cbae24f62922", 
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66" 
  },
  "transaction": {
    "id": "0daa380ba39596745",
    "type": "PURCHASE",
    "status":"AUTHORIZED|CLEARED|DECLINED|REVERSED|INVALID",
    "decline_reason": null|"",
    "local_amount":"123", 
    "local_currency":"EUR",
    "amount": "123",
    "currency": "EUR",
    "fx_rate": null,
    "mcc": "288",
    "counterparty_name": "Some Name"
  },
  "created_at": "2024-06-27 08:26:35",
  "updated_at": "2024-06-27 08:26:41"
}

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. In callbacks, transactions are identified by a combination of type and payment_method fields.

Buy

Buy with non-Spend card option (including mobile pay)

This is the case when purchase is made with the non-Spend card. type=buy, payment_method=card/mobile_pay

  1. new: a new transaction is created.
  2. pending: standing by for 3-D Secure verification.
  3. cancelled: a transaction is canceled usually due to the timeout.
  4. paid: the money deposited from a payment card.
  5. order_failed: a transaction is 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 Spend card option

This is the case when purchase is made with the Spend card (Fiat balance option in UI). type=buy, payment_method=spend

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, as well as in POS and e-commerce transactions. Contact your integration manager to enable this feature.

When the Fiat balance payment method is chosen by the end-user in the widget, the funds are transferred from the user’s card to the Spend card, and from there, the crypto purchase is made. If a user doesn’t already have a Spend card, one will be created for them with a zero balance. They’ll be able to top it up afterward.

  1. new: a new transaction is created; payment data is entered, awaiting processing.
  2. pending: card verification and 3D Secure processing are in progress.
  3. cancelled: a transaction is canceled (funds returned if charged).
  4. paid: a transaction is successfully completed.
  5. order_failed: a transaction is declined by card issuer/acquirer.
  6. order_scheduled: payment is authorized; standing by for the KYC verification.
  7. 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. type=buy, payment_method=invoice

  1. new: a new transaction is created.
  2. payment_initiated: callback for this event is triggered immediately after we create the payment request with the provider and send the redirect URL and payment instructions for further processing.
  3. completed: the crypto has been purchased on the Mercuryo side.
  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 is 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. cancelled: a transaction is 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 is created.
  2. pending: a transaction is in progress.
  3. completed: the money is transferred to the user address.
  4. failed: a transaction is failed.

Sell

Standard sell without the option of opening a Spend card

type=sell, payment_method=card

  1. new: a new transaction is created.
  2. pending: a transaction is in progress, payout processing is started.
  3. succeeded: the money is transferred to the card.
  4. failed: a transaction is failed (crypto will be returned to user).

Sell with Spend card option

This is the case when sell is made with the Spend card. type=sell, payment_method=spend_card_open

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, as well as in POS and e-commerce transactions. Contact your integration manager to enable this feature.

The difference from the standard sell is that this 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 is created.
  2. pending: a transaction is in progress, payout processing is started.
  3. succeeded: the money is transferred to the card.
  4. failed: a transaction is failed (crypto will be returned to user).
  5. cancelled: a transaction is cancelled (crypto will be returned to user).

Deposit

Standard Deposit

Deposit that follows the standard successful sell transaction, or goes before the sell+Spend card transaction.

  1. new: a new transaction is created.
  2. pending: a transaction is in progress.
  3. completed: the money is transferred to Mercuryo.
  4. failed: a transaction is failed (contact support required).

Deposit with Spend card during buy

Deposit that is triggered right after the buy+Spend card transaction becomes the new status. type=fiat_deposit, payment_method=spend_card_topup

This transaction type refers to a card-to-card transfer (top-up), meaning funds are added to the user's Spend card from another card. It is created when a user attempts to purchase cryptocurrency for an amount that exceeds the current balance on their Spend card.

  1. new: a new transaction is created; payment data is entered, awaiting processing.
  2. pending: card verification and 3D Secure processing are in progress.
  3. cancelled: a transaction is canceled (funds returned if charged).
  4. paid: a transaction is successfully completed.
  5. order_failed: a transaction is declined by card issuer/acquirer.
  6. order_scheduled: payment is authorized; standing by for the KYC verification.
  7. failed_exchange: Mercuryo failed to exchange for various reasons.

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 may include the following:

  • Identity verification document (passport, ID card, driving license, residence permit, proof of address).
  • Liveness test.

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

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.

Proof of Address

We do not accept bank statements from neobanks.

KYC Requirements by Feature and Country

Depending on the set of documents provided by the end user during the KYC process, different features (or combinations of features) become available.

The following features are supported based on the KYC documents provided:

  • crypto — feature for performing crypto operations
  • card — feature for opening and using the Spend card
  • ssn — feature for US residents to provide SSN (Social Security Number) in the widget without uploading any documents; in this case, they are allowed to buy crypto up to a certain limit via a simplified KYC flow. After reaching the limit, full KYC with the crypto feature is required.
Feature Country / Region Documents
crypto EU + EEA (for Native Apple Pay flow) ID card / passport / residence permit / driving licence + questionnaire + Selfie
crypto EU + EEA, and non-EU countries ID card / passport / residence permit / driving licence + Selfie
crypto US ID card / passport / residence permit / driving licence + SSN + Selfie
crypto RU (IP outside EEA) Passport / driving licence + POA + Selfie
crypto RU (IP within EEA) Passport / driving licence + residence permit + Selfie
crypto BR (DOC_FREE + Selfie scenario) CPF + Selfie
crypto BR (when DOC_FREE + Selfie scenario failed) ID card / passport / residence permit / driving licence + Selfie
card + crypto EU ID card / passport + POA + Selfie
ssn US POA as data + TIN

Integration

Important: When integrating the widget via iFrame, make sure to enable camera permissions in your iFrame code. This is required for users to access the camera during the KYC liveness test.

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.
  3. If you implement other 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

Important: This option is available only with approval from our Customer Success and Compliance teams, as SumSub charges for this service. Please discuss the details with Mercuryo business colleagues first before proceeding.

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. If in Sandbox mode, you don't want to wait for us to manually confirm the KYC review, use the test documents for which automatic processing is set up on the SumSub's side: Verification Document Templates.

Share Token Processing Rules

When using the SumSub share token, the following rules apply:

  1. Field mapping

    • Field sets may differ between systems. Field extraction is not based on field matching.
    • Only document types and allowed countries are considered during the matching process.

  2. Minimum requirement

    • The applicant must have completed at least:
      • Identity verification (ID document)
      • Liveness check (selfie)
    • The applicant must have an approved ("green") status on your side.
    • Additional verification steps are allowed, but only ID and Selfie are reused.

  3. Import behavior

    • If the minimum requirement is met, the applicant will be successfully imported.
    • Field differences and additional steps do not affect the import result.

  4. Matching logic

    • The share token flow is triggered by an email match.
    • Once matched, the applicant is imported based on ID and Selfie verification.

Partner Requirements

To use the share token flow, you must:

  • Provide the user's email, as it is used to match the applicant during the share token flow
  • Ensure the applicant has completed ID + Selfie verification
  • Include the share token in the request

Whitelisting Prerequisite

Before you can use the share token, you must complete the whitelisting process with SumSub and Mercuryo. If you skip these steps, you will not be able to use the share token.

  1. Conclude a contract with SumSub for the Reusable KYC feature.
  2. Request a partner token from your Mercuryo integration manager.
  3. Add the received partner token in SumSub.
    1. Log in to your SumSub account.
    2. Go to the Partners → Recipients tab.
    3. Click Add Recipient and enter the partner token.
  4. Ask your Mercuryo manager to verify the setup.

Steps

  1. Use https://api.sumsub.com/resources/accessTokens/-/shareToken to generate the shareToken parameter value.
  2. The applicantId and forClientId=Mercuryo parameters are required. Pass the generated value as shareToken parameter of the widget URL.

Submit Documents

Manually send us users' documents. Users will still be required to complete a liveness check through the widget.

Send us users' scanned documents.

All endpoints in this section require you to use API-based Authentication.

Steps

  1. Use GET /sdk-partner/user/kyc-status to get the KYC status. We can identify a user whom you registered by the email if we already have it:
    1. If in the list of features, the necessary feature is complete, then that’s it.
  2. Use POST /sdk-partner/kyc/docs to send the identity verification documents.
    1. Send us identity verification documents: ID card, driver license,passport, residence permit, proof of address (refer to the API Reference for the full list of required documents, and file naming conventions), feature and the country code of the user. The documents will be submitted to SumSub for verification.
    2. In response, the kyc_access_token property of data object will be received, which should be used later as share_token.
    3. Then it is required to pass standard silent sign-in authentication flow using POST /sdk-partner/login to get the init_token and init_token_type parameters.
    4. Afterwards, it is required to redirect the user to the widget, providing init_token and share_token parameters in the URL. Widget parameters:
      • initTokenType=sdkPartnerAuthorization
      • initToken=0a25dd714163a900
      • shareToken=yourKycAccessToken
  3. The user will be asked to provide the additional missing documents, if any, and do the liveness check directly in the widget.
  4. Use GET /sdk-partner/user/kyc-status to get the status for the necessary feature.
    1. Statuses:
      1. complete: KYC procedures are successfully complete.
      2. incomplete: SumSub hasn’t started the verification.
      3. failed_attempt: the first attempt to pass the verification failed. Try again.
      4. failed: the verification failed. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the documents. Appears only after the user has finished uploading and submitting all required documents and the verification process has started on SumSub’s side.
  5. After the KYC status becomes complete, or if the user needs to complete the liveness check in the widget:
    1. Use POST /sdk-partner/login to get the init_token and init_token_type parameters (see Silent Sign-In for details).
      • 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, providing init_token and share_token parameters in the URL. Widget parameters:
      • initTokenType=sdkPartnerAuthorization
      • initToken=0a25dd714163a900
      • shareToken=yourKycAccessToken

Silent Authentication

The silent authentication is a tool that makes signing in Mercuryo easier for users. In this method, merchants do not receive any information about their 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.

The user must accept the Terms of Service before signing up. You have to ask the user to agree to the Terms of Service on your front end. You will send user’s consent in the accept parameter of POST /sdk-partner/sign-up.

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.
  3. Display your widget.

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.

The user must accept the Terms of Service before signing up. You have to ask the user to agree to the Terms of Service on your front end. You will send user’s consent in the accept parameter of POST /sdk-partner/sign-up.

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.
  3. Display your widget.

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.
  3. Display your widget.

API-based Authentication

This method uses API calls to authenticate users. User information is shared with the merchant during the authentication process.

Note: These authentication methods are only applicable to the Submit Documents flow. They do not work for user login in the widget.

For the purpose of API-based authentication and authorization each submitted request must contain one of two tokens:

  • Sdk-Partner-Token - a token issued for a merchant and used when end-user is not yet authenticated (for sign-in requests).

  • Sdk-User-Token - a token received as a result of sign-in process and used for all user-specific requrests. Note: In the sign-in response, this token is returned as bearer_token property of data object, but it should be sent in the Sdk-User-Token header for subsequent requests.

The Sdk-User-Token expires in 24 hours for the Production environment. You can authorize the user again after that. The Sdk-User-Token doesn’t expire in the Sandbox environment.

For authentication of new and existing users, the same API and authorization processes are used. In case when a user with specified email does not exist yet, their account will be created. Thus, here and below only sign-in process is described.

The user must accept the Terms of Service before signing up. You have to ask the user to agree to the Terms of Service on your front end. You will send user’s consent in the accept parameter of POST /sdk-partner/user/sign-in-no-verify or POST /sdk-partner/user/sign-in.

For Sign-In request, Sdk-Partner-Token header must be included. Mercuryo uses the header to identify the merchant/user context.

There are two scenarios for user sign-in. For both of them, user's email is used as an identifier. Please check with your integration manager which scenario you can use.

  1. OTP-less Sign-In.
    • When user's email is considered as verified.
    • When user's email is considered to be unverified. In this case, user will have to verify it later, if needed.
  2. With OTP verification.

OTP-less Sign-In

This scenario assumes that a merchant validates user's email and identity, and no additional authentication is required.

Steps

  1. Ask your integration manager for the Sdk-Partner-Token, which is required for the following authentication endpoints.
  2. Use POST /sdk-partner/user/sign-in-no-verify to sign-in a user without OTP email verification.

Sign-In with OTP Verification

In the following scenario, a user must enter OTP submitted to their email.

Steps

  1. Ask your integration manager for the Sdk-Partner-Token, which is required for the following authentication endpoints.
  2. Use POST /sdk-partner/user/sign-in to start authentication process, providing user's email. As the result, OTP will be sent to the user in case of success.
  3. Use POST /sdk-partner/user/sign-in/verify to submit OTP, entered by the user.
    1. To resend OTP code for sign-in, use POST /sdk-partner/user/sign-in/verify/resend.

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. Display your widget. Also, you can preselect parameters.

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 refundAddress 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 the limits for a specific crypto/fiat pair and widget.
  5. Use GET /lib/limits/sell to get the list of limits for all enabled currencies.
  6. Use GET /widget/sell/rate to see the transaction total.
  7. Use GET /sdk-partner/transactions to get the transaction status.
  8. Display your widget. Also, you can preselect parameters.

Off-Chain in On-Off-Ramps

When users buy cryptocurrency with Mercuryo, a network fee (also known as a blockchain fee) is added, increasing the cost of transactions. This fee can sometimes double the transaction cost, leading to higher exchange rates or fees. To reduce transaction costs, the Off-Chain feature can be enabled. This feature processes transactions off-chain, completely eliminating the network fee.

To start using the Off-Chain feature, contact your integration manager.

You will need to register a Mercuryo business wallet, which allows you to collect and manage all crypto payments. Note that this type of wallet cannot be used to sell cryptocurrency. It is used to credit purchased cryptocurrency and to withdraw cryptocurrency to external wallets.

Steps

  1. Sign the Additional Terms & Conditions. If you’ve already provided Mercuryo with your company’s registration data, founder, and director information during the On-Off-ramps registration process, you don’t need to submit additional documents. Simply sign the consent for the document and return it via email.
  2. Create a Mercuryo wallet by registering here.
  3. Inform your integraton manager of the email used to register the wallet (i.e., the wallet email address). This email must be new and not previously used for Mercuryo services. The integration manager will set this wallet as a business wallet and disable the customer’s minimum commission parameter.
  4. In your wallet, get the address of the corresponding network to use in transactions instead of the end user’s address.

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
widgetFlow CONST recurrent Mandatory. Enables the recurring payment flow
partnerFlow Applicable to the partners having a customized UI
address {crypto_address} Destination address
currency {crypto_currency} Cryptocurrency
fixNetwork {crypto_network} Example: ETHEREUM, BINANCESMARTCHAIN, TRON
fiatCurrency {fiat_currency} Fiat currency
redirectUrl {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
chargeDay 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

Example

The sample below demonstrates how widget can be invoked in a merchant's portal.

mercuryoWidget.run({
    widgetId: "fb359d09-fff6-4b1f-906c-b9062b135065",
    host: document.getElementById("mercuryo-widget") widgetFlow: "recurrent",
    address: "0x32Be343B94f860124dC4fEe1c7B7B8B646F6D9F",
    currency: "ETH",
    fixNetwork: "ETHEREUM",
    fiatCurrency: "EUR"
});

In Sandbox environment, only GBP currency is available for testing.

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 and On-ramp processes. 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.

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.

Opening Spend Card during Off-ramp

Note: This scenario is currently unavailable.

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

  1. Turn on sell flow: as the type parameter, specify sell.
  2. Specify EUR as the fiatCurrency parameter.
  3. Specify the fiatAmount parameter.
  4. Add the paymentMethod parameter with the spend_card value.

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.

When the sell request is created with Spend card, first, we wait for deposit. When the deposit comes, the payout transaction in the new status is created. The difference from the standard sell is that this transaction in the new status is created after a successful deposit. In the standard sell, the transaction is created before the deposit.

Opening Spend Card during On-ramp

End-user Flow for Issuing New Mercuryo Spend Card

  1. User specifies the amount for Buy operation (fiat for crypto money).
  2. As the payment method, an option to use Fiat balance is chosen. This option is available, if the feature is enabled by integration manager. When the Fiat balance payment method is chosen, the funds are transferred from the user’s card to the Spend card, and from there, the crypto purchase is made. If a user doesn’t already have a Spend card, one will be created for them with a zero balance. They’ll be able to top it up afterward.
  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. When fiat amount is deducted from an issued user's Spend card, a cryptocurrency withdrawal is initiated for the user.
  7. Card details are displayed to the user once the card is loaded and ready.

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.

Passkey Feature

A passwordless login feature that makes the authorization process safer and easier. Instead of entering a password, user confirms the login using a fingerprint, Face ID, PIN code or similar method on their device.

Technical Limitations

  • The feature won’t work on iPhones, iPads, or Mac in Safari browsers.
  • The feature is also not available in WebView-based applications, as WebView does not support the required passkey APIs.
  • The feature is not called when logging in through partners using silent login.

End-user Flow for Passkey Feature

  1. After enabling the feature, the user must log in using:
  • code from email
  • or email code + password (if used).
  1. The user is asked to set a password or skip this option. If the user has not set a password, they will be asked about this option again each time they log in.
  2. Once a Passkey is set, it can be used instead of the email verification code. If needed, the email code is still available as a backup option.
  3. If a non-cloud key storage is used, the user must set a passkey on each platform (phone, computer) where the widget is used.
  4. If a user uses 1Password to log in via Passkey and switches to another device (for example, from a computer to a phone), a new Passkey must be added to the new device. It doesn't matter which one, the fact of creation is important. This will allow using the same code from 1Password to log in from different devices.

The user can set 10 different options as a passkey.

Control is available via the menu. Key names can be changed. The user can add new keys or remove unused ones.

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
  35. arctic
  36. dark_ch
  37. light_ch
  38. white_market
  39. exolix
  40. grapherex_light
  41. grapherex_dark
  42. haru_light
  43. haru_dark

To get Mercuryo fonts, download this archive.

To get Mercuryo logos, download this archive.

FAQ

Visit Help Center for Users and Help Center for Merchants

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.