About

Mercuryo On-Ramp & Off-Ramp API solution allows to exchange cryptocurrencies to fiat money directly in your app or on your website.

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.

Getting Started

Before using the Sandbox environment, prepare these:

• IP addresses to add to the whitelist.
• An email address to log in.

The Sandbox environment works with the following networks:

Contact your integration manager. You will get the sdk-partner-token to sign up user registration and authorization endpoints.

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.

API URL: https://sandbox-cryptosaas.mrcr.io/v1.6/.

All the requests must contain:

• Content Type: application/json
• Accept: application/json
• User Agent: {PartnerName}

Recommendations:

All Mercuryo API endpoints accept the B2B-User-Ip header, and it is strongly recommended that all requests contain the real IP address of end-user in this header. If there is no end-user's IP, Mercuryo reserves the right to reject transactions according to its internal rules.

User Fees

Mercuryo charges fees for:

• Exchanging fiat money to crypto.
• Exchanging crypto to fiat money.

Fee information must be available to the user at any moment.

You can include additional fees to the list: Mercuryo’s Fees + Your Fees = Total Fee. Contact your account manager to adjust the fee policy.

Sign-Up

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 /b2b/user/sign-up.

All Mercuryo API endpoints — except for the authorization endpoints — require b2b-bearer-token header. Mercuryo uses the header to identify the merchant/user context.

The b2b-bearer-token expires in 24 hours for the Production environment. You can authorize the user again or refresh the token after that. The b2b-bearer-token doesn’t expire in the Sandbox environment.

Steps

1. Ask your account manager to give you the sdk-partner-token.
2. Use the sdk-partner-token to sign authorization endpoints.
3. Use POST /b2b/user/sign-up to sign up a user.

Sign-In

Use POST /b2b/user/sign-in to sign in a user, or use GET /b2b/user/refresh-token to refresh the b2b-bearer-token.

Transaction ID

You can assign an ID to each transaction. Pass your transaction ID in the merchant_transaction_id field.

Transaction ID format: ^[A-Za-z0-9-_]{1,255}$. Any lowercase and uppercase letter of the Latin alphabet, digits, underscore, and hyphen. Total length is up to 255 characters.

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.

Note: Please be aware that there must be only one email address per user. That is, if the existing user (who is already registered and passed the KYC procedure with one email address) registers with another email address and provides the same documents to pass the KYC procedure, this user will receive the KYC refusal under the new email. Thus, email address used in user registration must be wisely chosen.

Identity Verification

These documents can be acceptable identity verification:

• Passport.
• ID card.
• Driving license.
• Residence permit.
• Proof of address.

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 Country

Depending on the user's country, a different set of documents is required for verification.

Integration

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.

SumSub Access Token

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

URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.

If redirect parameters are missing, the user won’t be redirected. status and msg parameters will be appended to failure_url. status: back - if user clicks the back button. status: fail - if you get an error.

Use GET /b2b/user/contacts to check user's email verification status.

Steps

1. Use GET /b2b/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, feature: crypto is complete, then that’s it.
2. Use GET /b2b/kyc/access-token to get the KYC access token.
3. Use a URL to redirect the user to Mercuryo.
   1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
   2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
      1. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
      2. 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.
4. Use GET /b2b/user/kyc-status to get the status for feature: crypto.
   1. Statuses:
      1. complete: KYC procedures are successfully complete.
      2. incomplete: not enough documents have been provided; 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.
   2. If the KYC status is incomplete or failed_attempt, re-take KYC.
      1. Use GET /b2b/kyc/access-token to get the KYC access token.
      2. Use a URL to redirect the user to Mercuryo.
         1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
         2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
            1. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
            2. 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.
5. Use GET /b2b/kyc/documents to fetch details on uploaded KYC documents.

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

If Mercuryo already has an applicant who requires verification, use POST /b2b/user/kyc-documents or GET /b2b/kyc/access-token to send additional documents. Or contact Mercuryo Support.

Use GET /b2b/user/contacts to check user's email verification status.

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 GET /b2b/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, feature: crypto is complete, then that’s it.
2. Use SumSub API https://api.sumsub.com/resources/accessTokens/-/shareToken?applicantId=<applicant-Id>&forClientId=Mercuryo and ClientID Mercuryo to get the share token.
3. Send the share token using POST /b2b/user/kyc-share-token. The response will include an access_token.
4. Use GET /b2b/user/kyc-status to get the status for feature: crypto.
   1. Statuses:
      1. complete: KYC procedures are successfully complete.
      2. incomplete: not enough documents have been provided; 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.
   2. If the KYC status is incomplete or failed_attempt, re-take KYC.
      1. Use the received access_token to redirect the user to the SumSub interface in order to provide additional information during the verification process.
      2. Use a URL to redirect the user to Mercuryo.
         1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
         2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
            1. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
            2. 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.
5. Use GET /b2b/kyc/documents to fetch details on uploaded KYC documents.

User's Date of Birth

To simplify the off-ramp process to external cards and increase the sales conversion, it is recommended to provide user's date of birth. Use GET /b2b/user/contacts to check if the date of birth is already set. If the value of the is_birthday_set property equals to false, use POST /b2b/user/birthday to submit user's date of birth. Please provide only the actual date of birth, not a random value.

Submit Documents

Manually send us users’ documents.

Send us users’ scanned documents.

Use GET /b2b/user/contacts to check user's email verification status.

Steps

1. Use GET /b2b/user/kyc-status to get the KYC status. We can identify a user who you registered by the email if we already have it:
   1. If in the list of features, feature: crypto is complete, then that’s it.
2. Use POST /b2b/user/kyc-documents to send the identity verification documents. The response will include a kyc_access_token.
   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), and the country code (for kyc_level=1). The documents will be submitted to SumSub for verification.
3. Use GET /b2b/user/kyc-status to get the status for feature: crypto.
   1. Statuses:
      1. complete: KYC procedures are successfully complete.
      2. incomplete: not enough documents have been provided; 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.
   2. If the KYC status is incomplete or failed_attempt, re-take KYC.
      1. Use the received kyc_access_token to redirect the user to the SumSub interface in order to provide additional information during the verification process.
      2. Use a URL to redirect the user to Mercuryo.
         1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
         2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
            1. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
            2. 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.
4. Use GET /b2b/kyc/documents to fetch details on uploaded KYC documents.

On-Ramp Scenarios

If you’re not PCI-DSS certified, you will have to use Mercuryo interface to acquire the payment card data. Mercuryo interface is customizable.

Payment Card Crypto Purchase

Buying crypto with fiat money using a payment card.

Use GET /b2b/user/contacts to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /b2b/user/card-limits to get limit details. Use GET /b2b/user/card-limits-unverified to check limits of the users who haven’t completed the KYC procedures.

Slippage

If the price changes 1% or more upon calling the endpoint after acquiring rates, then the endpoint will contain an error with the 403004 code reading "Conversion rate has been changed”: Mercuryo won't create a transaction. Otherwise, Mercuryo will cover the price difference and the trade will have the rate which was acquired.

Acquire rates again if the elapsed time is more than an hour, because trx_token expires in one hour.

Steps

1. Use GET /b2b/currencies to get available currencies.
2. Use GET /b2b/oor/buy-methods to get available purchase methods.
3. Use the card payment method to buy crypto with user’s payment card.
4. Use GET /b2b/oor/buy-rates to get rates.
   1. The rates will be frozen and associated with the trx_token.
5. Use GET /b2b/user/cards to get user’s saved payment cards. All new payment cards are saved automatically.
6. (Optional) Use GET /b2b/user/contacts to ensure that the user's billing address is present.
   1. If the value of the is_billing_address_set property equals to false, use POST /b2b/user/billing-address to submit user's billing address.
7. Use POST /b2b/oor/buy to start the transaction.
   1. Mercuryo creates the buy_card transaction.
   2. You will get a link to redirect the user. URL example: https://payments.mrcr.io/buy?parameters.
   3. User will be prompted to enter their billing address unless you explicitly send the billing address before finalizing the transaction via POST /b2b/oor/buy.
   4. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration manager to set the URL.

Get the transaction status using GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}.

Crypto Purchase for PCI-DSS Certified

Buying crypto with fiat money using a payment card.

The user must be signed in and verified (valid KYC). Mercuryo won’t complete the transaction if the verification is expired. Use GET /b2b/user/kyc-status to check user’s verification.

Use GET /b2b/user/contacts to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /b2b/user/card-limits to get limit details.

Steps

1. Use GET /b2b/currencies to get available currencies.
2. Use GET /b2b/oor/buy-methods to get available purchase methods.
3. Use the card payment method to buy crypto with user’s payment card.
4. Use GET /b2b/oor/buy-rates to get rates.
   1. The rates will be frozen and associated with the trx_token.
5. Use GET /b2b/user/cards to get user’s saved payment cards. All new payment cards are saved automatically.
6. Use GET /b2b/user/contacts to ensure that the user's billing address is present.
   1. If the value of the is_billing_address_set property equals to false, use POST /b2b/user/billing-address to submit user's billing address.
7. Use POST /b2b/oor/buy to start the transaction. For users with Brazil-issued payment cards and Brazilian reals only: pass the tin parameter in POST b2b/oor/buy/card. A Taxpayer Identification Number — which is CPF for Brazil — is required.
   1. POST b2b/oor/buy/card returns a 3-D secure redirect. This redirect contains uri_template. Redirect the user to the URL from uri_template and pass the parameters of the 3-D secure redirect.
   2. Create an iframe in your app to connect to the domain specified in the src attribute. Wait till onLoad is finished and pass the 3-D secure object in the iframe. Process the message at the front end after the 3-D secure form is complete.
   3. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration specialist to set the URL.

Get the transaction status using GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}.

Off-Ramp Scenarios

If you’re not PCI-DSS certified, you will have to use Mercuryo interface to acquire the payment card data. Mercuryo interface is customizable.

Payment Card 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. Use GET /b2b/user/kyc-status to check user’s verification.

Use GET /b2b/user/contacts to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /b2b/user/card-limits to get limit details.

Slippage

Wait for a deposit after successfully using POST /b2b/oor/sell. If the price changes upon receiving a deposit more than 5%, Mercuryo won't create a transaction. Mercuryo will return the deposit. Otherwise, Mercuryo will cover the slippage and the trade will have the rate which was acquired.

Acquire rates again if the elapsed time is more than an hour, because trx_token expires in one hour.

Steps

1. Use GET /b2b/currencies to get available currencies.
2. Use GET /b2b/oor/sell-methods to get available sell methods.
3. Use the card payment method to sell crypto and withdraw funds to user’s payment card.
4. Use GET /b2b/oor/sell-rates to get rates.
   1. The rates will be frozen and associated with the trx_token.
5. Use GET /b2b/user/cards to get user’s saved payment cards. All new payment cards are saved automatically.
6. Use POST /b2b/oor/sell to get a link to redirect the user.
   1. You will get a link to redirect the user. URL example: https://payments.mrcr.io/sell?parameters.
   2. You will get an address to deposit crypto in the GET parameter of the redirect after successfully binding the payment card. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration specialist to set the URL.
   3. Mercuryo creates the sell_card transaction after receiving crypto. If the sell_card transaction fails, Mercuryo will return crypto to the specified address within two hours.
7. Get the address parameter value from the URL — which is a blockchain wallet — to send the crypto.
   1. Check the signature parameter value from the URL. It must be the same as the generated hash made up of address and merchant_transaction_id values in JSON, ex. [”address”:”crypto_address”,“merchant_transaction_id”:”123”]. This is a security measure to prevent the money theft.

Get the transaction status using GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}.

Crypto Sell for PCI-DSS Certified

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. Use GET /b2b/user/kyc-status to check user’s verification.

Use GET /b2b/user/contacts to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /b2b/user/card-limits to get limit details.

Steps

1. Use GET /b2b/currencies to get available currencies.
2. Use GET /b2b/oor/sell-methods to get available sell methods.
3. Use the card payment method to sell crypto and withdraw funds to user’s payment card.
4. Use GET /b2b/oor/sell-rates to get rates.
   1. The rates will be frozen and associated with the trx_token.
5. Use GET /b2b/user/cards to get user’s saved payment cards. All new payment cards are saved automatically.
6. Use POST /b2b/oor/sell/card to get the address for depositing crypto.
   1. POST /b2b/oor/sell/card returns a 3-D secure redirect object. This redirect contains uri_template. Redirect the user to the URL from uri_template and pass the parameters of the 3-D secure redirect.
   2. Mercuryo creates the sell_card transaction after receiving crypto.
      1. If the sell_card transaction fails, Mercuryo will return crypto to the specified address within two hours.
   3. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration specialist to set the URL.

Get the transaction status using GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}.

Transactions

Buy with card option

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

1. pending: a transaction is in progress.
2. failed: a transaction is failed.
3. cancelled: a transaction is cancelled by the user or system.
4. succeeded: a transaction is successfully completed.

Sell with card option

This is the case when selling crypto for fiat money is made with the withdrawal of funds to a payment card.

1. pending: a transaction is in progress.
2. failed: a transaction is failed.
3. cancelled: a transaction is cancelled by the user or system.
4. succeeded: a transaction is successfully completed.

Callbacks

Сontact your integration manager to set the callback URL.

Body

{
"url": "https:\/\/webhook.site\/#!\/6a4e734e-6c46-4de0-b67e-0166681aa250",
"tries": 15,
"payload": {
"data": {
"type": "buy",
"amount": "0.00239598",
"status": "paid",
"address": null,
"currency": "BTC",
"user_uuid": "447efa32-0afc-4326-b474-21e5a8624ce1",
"created_at": "2022-12-12 09:31:44",
"updated_at": "2022-12-12 09:32:08",
"fiat_amount": "40.00",
"fiat_currency": "EUR",
"merchant_transaction_id": "09516f6c766427412"
},
"eventId": "316e4fba-99bb-4322-8703-35542f477390"
},
"sign_key": "vjuKGL4fxMF6csD-3cr724TWPUPNTa8N",
"widget_id": "406a71aa-cc5f-471b-971b-6047dac6173f"
}

FAQ

Visit Help Center

1. What crypto currencies does Mercuryo Support?

Supported cryptocurrencies.

2. What crypto networks does Mercuryo Support?

Supported crypto networks.

3. 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:

- End-user's IP address.
- End-user’s card issuer country.
- 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.

4. Can I receive several callbacks of the same transaction with several statuses at the same time? Ex.: one transaction, one callback that is completed and another callback that is pending?

We send callbacks asynchronously. The callback delivery according to the status change is not guaranteed.

5. Is there “retry” for a failed callback? How does it work? Can I adjust it?

Yes, there is “retry”. You cannot adjust it. If the callback URL request doesn't return 200, we will be sending more requests asynchronously, but fewer with each day.

6. How is sign_key formed? How do I verify it?

We send the X-Signature header with a callback. This header contains the sha256 hash generated from JSON of the entire POST request. sign_key is used as a key. Please contact your integration manager to obtain sign_key. You can verify a callback by encoding the received callback with the sha256 algorithm and a key from the widget, and comparing the hash with the one from the header.

7. What is the time zone for created_at and updated_at?

The time zone is UTC.

8. Do you use POST to send callbacks?

Yes, we use POST to send callbacks.

9. When exactly do I receive callbacks?

You receive callbacks upon creating a transaction and a status change.

10. What do my server respond to a callback for it to be considered received?

You server must respond with the 200 http code.

11. What happens if a crypto sell transaction fails because the transfer takes too long?

It is assumed that a sell transaction must be completed within 6 hours. If the crypto is not received within this time, the transaction will be marked as failed due to a timeout. If the crypto is received after the 6-hour period, Mercuryo will return the crypto to the user's address.