Mercuryo Banking-as-a-Service API is a white label solution which allows for creating crypto-friendly IBANs for individuals in your app. An IBAN account is opened in individual’s name. The user can store funds in the IBAN account, transfer funds to other IBANs via SEPA and SEPA Instant, and instantly buy cryptocurrencies using the IBAN.

The International Bank Account Number (IBAN) is an internationally agreed system of identifying bank accounts across national borders to facilitate the communication and processing of cross border transactions with a reduced risk of transcription errors.

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, and credentials to access the Administration Dashboard.

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

Administration Dashboard URL: https://partners.mrcr.io/site/login.

Mercuryo charges fees for:

• Withdrawing fiat money from user’s IBAN.
• Depositing fiat money to user’s IBAN.
• 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 the 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.

We support: European Economic Area (EEA), European Union (EU), Switzerland, United Kingdom (UK), other countries.

We do not support: Abkhazia, Afghanistan, Aland Islands, Angola, Algeria, American Samoa, Antarctica, Barbados, Bangladesh, Burundi, Bolivia, Burkina Faso, Burma, Central African Republic, Cote d'Ivoire (Ivory Coast), Congo, Crimea, Donetsk, Luhansk, China, Chile, Colombia, Costa Rica, Cuba, Cambodia, Cayman Islands, Democratic Republic of the Congo, Ecuador, Eritrea, Ethiopia, Fiji, French Guiana, French Polynesia, Guam, Guatemala, Guinea, Guinea-Bissau, Honduras, Haiti, Iraq, Iran, Iceland, Islamic Republic, Jamaica, Jordan, Kuwait, Kyrgyzstan, Laos, Lebanon, Liberia, Libya, Morocco, Mali, Myanmar, North Korea, North Macedonia, Nicaragua, Northern Mariana Islands, Nepal, South Ossetia, Panama, Peru, Papua New Guinea, Pakistan, Palau, Palestine, Puerto Rico, Republic of the Congo, Republic of Guinea-Bissau, Senegal, Saudi Arabia, Sudan, Sierra Leone, Somalia, South Sudan, Sri Lanka, Syria, The Bahamas, Tunisia, Transnistria, Trinidad and Tobago, Uganda, US Virgin Islands, Vanuatu, Venezuela, Kosovo, Yemen, Zimbabwe, United States.

Verification for:

• EEA, EU, Switzerland, UK:
  • Passport with citizenship or ID card with citizenship.
  • Proof of address.
  • Liveness test.
• Other countries:
  • Passport with citizenship or ID card with citizenship.
  • Proof of address (EEA, EU, Switzerland, UK).
  • Residence permit (EEA, EU, Switzerland, UK).
  • Liveness test.

These documents can be acceptable identity verification:

• Passport.
• ID card (both sides).

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.

We do not accept bank statements from neobanks.

These documents can be acceptable proof of address:

• Bank statement or credit/debit card statement.
• Utility bill (excluding mobile phone bills).
• Rental or lease agreement.
• Residency certificate.

The document must have:

• Full name.
• Full residential address.
• Date of issue.

Meet these requirements:

• The document must be issued within the last three months.
• All the information must be clear and readable.

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

1. If you don’t implement any KYC procedures.
2. If you implement SumSub KYC procedures.
3. If you implement other 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/user/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.

Steps

1. Use GET /b2b/user/data to get the KYC status. We can identify a user who you registered by the email if we already have it:
   1. If kyc2_status is complete, then that’s it.
   2. If kyc1_status is complete but kyc2_status is not, proceed with the next step.
2. Use GET /b2b/user/kyc-access-token with kyc_level=2 to get the KYC access token.
3. Use a URL to redirect the user to Mercuryo.
   1. The Production environment URL example: https://payments.mrcr.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/data to get the kyc2_status parameter.
   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/user/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/user/kyc-access-token to send additional documents. Or contact Mercuryo Support.

Steps

1. Use GET /b2b/user/data to get the KYC status. We can identify a user who you registered by the email if we already have it:
   1. If kyc2_status is complete, then that’s it.
   2. If kyc1_status is not complete, use POST /b2b/user/kyc-documents to send additional documents for existing Mercuryo SumSub applicants. Or send the documents to Mercuryo Support.
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 with kyc_level=2.
4. Use GET /b2b/user/data to get the kyc2_status parameter.
   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/user/kyc-documents to fetch details on uploaded KYC documents.

Manually send us users’ documents.

Send us users’ scanned documents. Still, the users will have to do the liveness test in the SumSub interface.

Steps

1. Use GET /b2b/user/data to get the KYC status. We can identify a user who you registered by the email if we already have it:
   1. If kyc2_status is complete, then that’s it.
   2. If kyc1_status is complete but kyc2_status is not, proceed with the next step.
2. Use POST /b2b/user/kyc-documents to send the identity verification.
   1. Send us the identity verification: a passport or ID card (see instructions for file naming in API Reference) and the country of the document (country_code parameter).
3. Use POST /b2b/user/kyc-documents to send the proof of address.
   1. Send us the proof of address: a bank statement or credit/debit card statement, utility bill (excluding mobile phone bills), rental or lease agreement, residency certificate. You may have to send the residence permit (see your country in the list).
4. Use GET /b2b/user/data to get kyc2_status parameter.
   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/user/kyc-documents to fetch details on uploaded KYC documents.

The user verifies the phone number. If you collect and verify phone numbers, we will treat them as verified. If you don’t, Mercuryo will verify phone numbers with a text message. Setting up and updating the phone number is done the same way.

Steps

1. Use POST /b2b/user/set-phone to set up a phone number in the international format.
2. Use GET /b2b/user/data to get the phone verification status.

The user must successfully complete KYC procedures and have a verified mobile phone number to open an IBAN. You can create only one IBAN for one user.

Check these before creating an IBAN:

• country_code must be on the white list. SumSub can change this when processing the documents.
• phone must be set up and phone_status must be verified.
• kyc2_status must be complete.

Steps

1. Use POST /b2b/user/iban to create an IBAN.
2. Use GET /b2b/user/iban to get user’s IBAN details.

Toping up a Mercuryo IBAN with fiat money using another IBAN.

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

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

Steps

1. Use GET /b2b/user/iban to get user’s IBAN details.
2. Share the Mercuryo IBAN details with the user.
3. The user deposits fiat money to the Mercuryo IBAN.
   1. Mercuryo creates the fiat_deposit transaction.
   2. Mercuryo creates the iban_charge transaction if the fee is set for the fiat deposit, or if the monthly fee is set (charged every fifth day every month).

See user transactions using GET /b2b/transactions.

Withdrawing fiat money from a Mercuryo IBAN to another IBAN.

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

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

Use GET /b2b/fiat/withdraw-estimate-fee to get fee details.

Steps

1. Use POST /b2b/fiat/withdraw to start the transaction.
   1. Mercuryo creates the fiat_withdraw transaction. The transaction will be canceled in two hours if it’s not confirmed with a confirmation code.
   2. Mercuryo creates the iban_charge transaction if the fee is set for the fiat withdrawal, or if the monthly fee is set (charged every fifth day every month).
   3. The user receives an email with a confirmation code.
2. Use POST /b2b/fiat/verify-withdraw to confirm the transaction: submit the confirmation code.
   1. If the code expired, use POST /b2b/fiat/verify-withdraw/resend to resend the confirmation code.

See user transactions using GET /b2b/transactions.

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

Buying crypto with fiat money using a Mercuryo IBAN.

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

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /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/fiat/buy-rates/iban-exchange to get rates.
   1. The rates will be frozen and associated with trx_token.
3. Use POST /b2b/fiat/buy/iban-exchange to start the transaction.
   1. Mercuryo creates the buy_iban transaction. The transaction will be canceled if the rate changes more than 0.1%.

See user transactions using GET /b2b/transactions.

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/data to check user’s verification.

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/fiat/sell/iban-exchange. 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/fiat/sell-rates/iban-exchange to get rates.
   1. The rates will be frozen and associated with the sell token.
3. Use POST /b2b/fiat/sell/iban-exchange to get the address for depositing crypto.
   1. Mercuryo creates the sell_iban transaction after receiving crypto. The transaction will be canceled if the rate changes more than 0.1%. The transaction will be canceled in two hours if it’s not confirmed with a confirmation code.

See user transactions using GET /b2b/transactions.

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

Transaction	Statuses	Scenario
fiat_deposit	succeeded, failed.	IBAN Top-Up
fiat_deposit_refund	succeeded	IBAN Top-Up
iban_charge	pending, succeeded, failed, need_verify.	IBAN Top-Up, IBAN Withdrawal.
fiat_withdraw	pending, succeeded, failed, need_verify.	IBAN Withdrawal
fiat_withdraw_refund	succeeded	IBAN Withdrawal
iban_charge_refund	succeeded	IBAN Withdrawal
buy_iban	pending, succeeded.	Crypto Purchase
sell_iban	pending, succeeded, failed, failed_send, need_verify.	Crypto Sell

Sometimes, Mercuryo refunds Mercuryo IBAN transactions.

Transaction	Refund Transaction
buy_iban	buy_iban_refund
sell_iban	sell_iban_refund
fiat_deposit	fiat_deposit_refund
fiat_withdraw	fiat_withdraw_refund
iban_charge	iban_charge_refund

The iban_charge_refund transaction is for refunding the fee.

Every [transaction]_refund transaction relates to the normal transaction. Use GET /b2b/transactions to display the transactions. Find merchant_transaction_id of the related transaction in the related_transaction field.

Every normal transaction with a refund is linked to [transaction]_refund. Find merchant_transaction_id of a refund transaction in the related_refund field.

If Mercuryo refunds a transaction, you will get an additional [transaction]_refund transaction. And if there was the fee, you will get the additional iban_charge_refund transaction.

If the user bank rejects a transaction, you will only get an additional [transaction]_refund transaction.

Set up a callback URL for the selected widget to get callbacks.

• To browse callbacks, go to Administration Console > Widget Callbacks.
• To edit the URL for receiving callbacks, go to Administration Console > My Widgets > Actions > Update.

Scenario	Callback	Statuses
IBAN Top-Up	fiat_deposit	succeeded, failed.
IBAN Withdrawal	fiat_withdraw	pending, succeeded, failed, need_verify.
IBAN Withdrawal	fiat_withdraw_refund	succeeded.
Crypto Purchase	fiat_buy	pending, completed.
Crypto Purchase	withdraw	pending, succeeded, failed.
Crypto Sell	deposit	paid, refunded, failed.
Crypto Sell	fiat_sell	pending, completed, failed.

Body

{
"data": {
"amount": "0.00200000",
"fiat_amount": "27.72",
"created_at": "2023-01-03 09:59:28",
"updated_at": "2023-01-03 09:59:29",
"address": null,
"type": "fiat_sell",
"merchant_transaction_id": "096e76a911b723334",
"currency": "BTC",
"fiat_currency": "EUR",
"status": "pending",
"user_uuid": "d8799944-9c33-4f1d-95c6-cd88f2088f77"
},
"eventId": "5174de4e-fe84-4fc3-9c9e-72b688a3e76d"
}

Visit Help Center

What crypto currencies does Mercuryo Support?

Supported cryptocurrencies.

What crypto networks does Mercuryo Support?

Supported crypto networks.

Why can’t I create an IBAN?

Use POST /b2b/user/iban to create an IBAN. It’s POST not GET.

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 in the Administration Dashboard?

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 — which is set up in the Administration Dashboard — is used as a 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.