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

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:

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

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

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.

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

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.

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.

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

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.

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 e-mail address per user. That is, if the existing user (who is already registered and passed the KYC procedure with one e-mail address) registers with another e-mail address and provides the same documents to pass the KYC procedure, this user will receive the KYC refusal under the new e-mail. Thus, e-mail address used in user registration must be wisely chosen.

These documents can be acceptable identity verification:

• Passport.
• ID card.
• Driving license.

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 two cases for integrating KYC procedures depending on your user onboarding:

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

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

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.

Parameter	Description	Type
access_token	Get the access token using GET /b2b/kyc/access-token.	Required
success_url	URL-encoded JSON. Example: https://mercuryo.success.com.	Required
failure_url	URL-encoded JSON. Example: https://mercuryo.failure.com.	Required
scheme	Light or Dark appearance.	Optional
lang	The language is English by default. Supported languages: English, Chinese, Russian, French, Hindi, Indonesian, Japanese, Korean, Portuguese, Spanish, Turkish, Vietnamese.	Optional

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&scheme=your_scheme&lang=lang_code.
   2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token8&scheme=your_scheme&lang=lang_code.
   3. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
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: SumSub hasn’t started the verification.
      3. failed_attempt: the first attempt to pass the verification failed. Try again.
      4. failed: the verification failed; the user isn’t allowed to create an IBAN. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the documents.
5. Use GET /b2b/kyc/documents to fetch details on uploaded KYC documents.

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

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.
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: SumSub hasn’t started the verification.
      3. failed_attempt: the first attempt to pass the verification failed. Try again.
      4. failed: the verification failed; the user isn’t allowed to create an IBAN. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the documents.
5. Use GET /b2b/kyc/documents to fetch details on uploaded KYC documents.

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

You can enable the EUR 700 limit feature for crypto purchases with a payment card. A user will be able to buy crypto with a payment card until the limit of EUR 700 is reached. Contact your account manager to enable this feature. If the feature is enabled, use GET /b2b/user/card-limits-unverified to check user limits of the users who haven’t completed the KYC procedures.

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.

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

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

Buying crypto with fiat money.

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 /b2b/user/iban-limits/buy to get limit details.

Slippage

If the rate changes more than 1%, the trade will have the new rate. If the rate changes less than 1%, the trade will have the old rate.

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 iban_invoice 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 POST /b2b/oor/buy/iban-invoice to start the transaction.
   1. Mercuryo returns payment details and invoice_id.
   2. Mercuryo creates the buy_iban_invoice transaction after receiving the funds of the correct amount with invoice_id stated in the payment purpose.

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

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

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

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

Selling crypto and withdraw fiat money to user’s IBAN.

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/iban-limits/sell 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 iban method to sell crypto and withdraw funds to user’s IBAN.
4. Use GET /b2b/oor/sell-rates to get rates. The rates will be frozen and associated with the sell token.
5. Use POST /b2b/oor/sell/iban to get the address for depositing crypto.
   1. Mercuryo creates the sell_iban transaction after receiving crypto.
      1. If the sell_iban transaction is failed_send, use POST /b2b/oor/sell/iban/resend to resend the failed transaction.
      2. If the sell_iban transaction fails before transferring fiat money, Mercuryo will return crypto to the specified address within two hours.

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

Transaction	Statuses	Scenarios
buy_card		Payment Card Crypto Purchase
buy_iban_invoice		Bank Transfer Crypto Purchase
sell_card		Payment Card Crypto Sell, Crypto Sell for PCI-DSS Certified
sell_iban	pending, succeeded, failed, failed_send.	IBAN Crypto Sell

С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"
}

Visit Help Center

What crypto currencies does Mercuryo Support?

Supported cryptocurrencies.

What crypto networks does Mercuryo Support?

Supported crypto networks.

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.

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.

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.

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.

What is the time zone for created_at and updated_at?

The time zone is UTC.

Do you use POST to send callbacks?

Yes, we use POST to send callbacks.

When exactly do I receive callbacks?

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

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

You server must respond with the 200 http code.

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

It is assumed that a sell transaction must be completed for 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.