Banking-as-a-Service (1.6.0)

About

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.

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:

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.

User Fees

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.

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

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

Supported Countries

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, 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, Islamic Republic of Iran, Jamaica, Jordan, Kuwait, Kyrgyzstan, Laos, Lebanon, Liberia, Libya, Morocco, Mali, Myanmar (Burma), 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.

Identity Verification

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.

Proof of Address

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.

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.

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 and phone 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: iban is complete, then that’s it.
    2. If in the list of features, feature: crypto is complete but feature: iban is not, proceed with the next step.
  2. Use GET /b2b/kyc/access-token with feature: iban 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/kyc-status to get the status for feature: iban.
    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.

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 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 and phone 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: iban is complete, then that’s it.
    2. If in the list of features, feature: crypto 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/kyc-status to get the status for feature: iban.
    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.

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

Use GET /b2b/user/contacts to check user's email and phone 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: iban is complete, then that’s it.
    2. If in the list of features, feature: crypto is complete but feature: iban 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/kyc-status to get the status for feature: iban.
    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.

Phone Verification

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/contacts to get the phone verification status.

IBAN

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 confirmed.
  • feature: iban 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.

Scenarios

IBAN Top-Up

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

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

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.

IBAN Withdrawal

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

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

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

Crypto Purchase

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

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

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

Crypto Sell

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 and phone 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/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}.

Transactions

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

Refunding

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.

Callbacks

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

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

FAQ

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.

Helper

/b2b/currencies

Get supported currencies filtered for partner

Securitysdk-partner-token
Responses
200

OK

403

Error codes:
* 403003: Too many requests;

500

500000: Various reasons, check the message field

get/b2b/currencies
Response samples
application/json
{}

/b2b/rates

Get buy and sell rates for multiple cryptocurrencies at once

Securitysdk-partner-token
Request
query Parameters
is_amount_without_fee
boolean
Default: false

Return rates without fee included

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

500

500001: Various reasons, check the message field

get/b2b/rates
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/transactions

B2B transactions list

Securityb2b-bearer-token
Request
query Parameters
merchant_transaction_id
string

Merchant transaction id

date_start
string

Unix Timestamp search from

date_end
string

Unix Timestamp search end

status
string

Transaction status

show_retries
boolean

Show retries transactions

limit
string
Default: "50"

Limit of rows max 50, min 5

offset
string

Number of rows to skip

Responses
200

OK

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/transactions
Response samples
application/json
{
  • "data": [
    ],
  • "next": "string",
  • "prev": "string",
  • "status": "200",
  • "total": "100"
}

/b2b/validate-iban

Validate provided IBAN

Securitysdk-partner-token
Request
query Parameters
iban
required
string

IBAN to validate

Responses
200

OK

400

Error codes:
* 400001: Validation error;

401

401000: Authorization failed

405

405000: Method Not Allowed

500

500000: Various reasons, check the message field

get/b2b/validate-iban
Response samples
application/json
{
  • "data": { },
  • "status": "200"
}

/b2b/validate-wallet

B2B validate wallet

Securityb2b-bearer-token
Request
query Parameters
currency
required
string

Crypto currency

address
required
string

Wallet address to check

network
string

Network of currency

Responses
200

OK

400

Error codes:
* 400000: Bad request;
* 400001: Validation error, check the data field;

405

405000: Method Not Allowed

get/b2b/validate-wallet
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

Buy

/b2b/fiat/buy-rates/iban-exchange

Get rates for on-ramp transaction

Securityb2b-bearer-token
Request
query Parameters
from
required
string

Fiat currency code for sale

to
required
string

Cryptocurrency code for buy

amount_from
string

The total amount, including fees, to be converted into cryptocurrency, required if 'amount_to' empty

amount_to
string

The total amount, including fees, to be received in cryptocurrency, required if 'amount_from' empty

network
string

Cryptocurrency network, if empty default used (default and allowed networks described in /b2b/currencies)

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data or message fields;
* 400003: Currency is not supported;
* 400007: Antifraud error. Amount off limits;
* 400011: Validation error for from field;
* 400012: Validation error for to field;
* 400014: Empty widget error. Contact your account manager;
* 400070: Validation error for amount_from field;
* 400071: Validation error for amount_to field;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support
* 403034: Country is not supported for this operation;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/fiat/buy-rates/iban-exchange
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/fiat/buy/iban-exchange

Create on-ramp transaction

Securityb2b-bearer-token
Request
query Parameters
trx_token
required
string

Buy token returned by /b2b/fiat/buy-rates/iban-exchange, endpoint

address
required
string

The address to which the crypto should be transferred

merchant_transaction_id
string

Custom ID for checking transaction status. If empty, it will be generated

Responses
200

OK

400

Error codes:
* 400000: Unable to finish antifraud check of transaction. Try again later
* 400001: Validation error, check the data field;
* 400007: Antifraud check error, amount off limits;
* 400048: Unsupported payment alias;
* 400049: IBAN not found;
* 400055: Cannot exchange currencies by server error. Check the message field;
* 400083: IBAN has been deactivated.;

401

401000: Authorization failed

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/fiat/buy/iban-exchange
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

Sell

/b2b/fiat/sell-rates/iban-exchange

Get rates for off-ramp transaction

Securityb2b-bearer-token
Request
query Parameters
from
required
string

Cryptocurrency code for sale

to
required
string

Fiat currency code for buy

amount_from
string

The total amount of cryptocurrency for sale, including fees, required if 'amount_to' empty

amount_to
string

The total amount, including fees, to be received in fiat currency, required if 'amount_from' empty

network
string

Cryptocurrency network, if empty default used (default and allowed networks described in /b2b/currencies)

Responses
200

OK

400

Error codes:
* 400000: Inner HTTP exception. Please contact support;
* 400001: Validation error, check the data or message fields;
* 400003: Currency is not supported;
* 400007: Antifraud error. Amount off limits;
* 400011: Validation error for from field;
* 400012: Validation error for to field;
* 400014: Empty widget error. Contact your account manager;
* 400070: Validation error for amount_from field;
* 400071: Validation error for amount_to field;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support
* 403034: Country is not supported for this operation;

500

500001: Various reasons, check the message field

get/b2b/fiat/sell-rates/iban-exchange
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/fiat/sell/iban-exchange

Create off-ramp transaction

Securityb2b-bearer-token
Request
query Parameters
trx_token
required
string

Sell token returned by /b2b/fiat/sell-rates/iban-exchange endpoint

address
string

Address for returning cryptocurrency in case of an error in the transaction

merchant_transaction_id
string

Custom ID for checking transaction status. If empty, it will be generated.

Responses
200

OK

400

Error codes:
* 400000: Unable to finish antifraud check of transaction. Try again later
* 400001: Validation error, check the data field;
* 400007: Antifraud check error, amount off limits;
* 400048: Unsupported payment alias;
* 400049: IBAN not found;
* 400083: IBAN has been deactivated.;

401

401000: Authorization failed

403

Error codes:
* 403001: Kyc verification needed;
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403021: Country is not supported;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/fiat/sell/iban-exchange
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

Withdraw

/b2b/fiat/verify-withdraw

Verify IBAN withdraw by sms or e-mail

Securityb2b-bearer-token
Request
Request Body schema: application/json
required
code
required
string

code, received by sms or e-mail

key
required
string

Verification key from b2b/fiat/withdraw

Responses
200

OK

400

Error codes:
* 400000: Various reasons. Try again later;
* 400001: Validation error, check the data field;
* 400054: IBAN error. Check the message field;

401

Error codes:
* 401000: Authorization failed;
* 401001: Verification code is invalid;

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403025: Withdraw not found;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/fiat/verify-withdraw
Request samples
application/json
{
  • "code": "string",
  • "key": "string"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/fiat/verify-withdraw/resend

BAAS resend verification code for withdraw

Securityb2b-bearer-token
Request
Request Body schema: application/json
required

JSON Body

key
required
string

Verification key from /b2b/fiat/verify-withdraw

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;

405

405000: Method Not Allowed

post/b2b/fiat/verify-withdraw/resend
Request samples
application/json
{
  • "key": "2e6c5cd472e47452b5639e527ef456f8bf0a87a6d4ff9bbbf558685f86caf90bd2l0aGRyYXc=AM5qhGGzacPx47vClCLA44tGdrIaAFfI"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/fiat/withdraw

Create IBAN withdraw transaction

Securityb2b-bearer-token
Request
Request Body schema: application/json
required

Request data

address
required
string

Beneficiary's address

amount
required
string

Amount for withdrawal

beneficiary_iban
required
string

Beneficiary's IBAN number

city
required
string

Beneficiary's city

country_code
required
string

Beneficiary's country code consisting of 2 letters

currency
required
string
Default: "EUR"

Withdrawal currency

full_name
required
string

Beneficiary's full name

merchant_transaction_id
string

Client unique ID (If empty - generate from random)

purpose
required
string

Purpose for withdrawal

swift
required
string

Beneficiary's swift number

Responses
200

OK

400

Error codes:
* 400000: Various reasons. Please contact support;
* 400001: Validation error, check the data field;
* 400007: Antifraud check failed. Amount off limits;
* 400049: IBAN not found;
* 400050: IBAN is not available for user;
* 400066: Unknown error;
* 400083: IBAN has been deactivated;

401

401000: Authorization failed

403

Error codes:
* 403003: Request for verification token is too frequent. Try again later;
* 403005: Not enough funds;
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

Error codes:
* 500000: Various reasons. Please contact support
; * 500001: Various reasons. Please contact support;

post/b2b/fiat/withdraw
Request samples
application/json
{
  • "address": "string",
  • "amount": "string",
  • "beneficiary_iban": "string",
  • "city": "string",
  • "country_code": "string",
  • "currency": "EUR",
  • "full_name": "string",
  • "merchant_transaction_id": "string",
  • "purpose": "string",
  • "swift": "string"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/fiat/withdraw-estimate-fee

Get rates for IBAN transaction

Securityb2b-bearer-token
Request
query Parameters
currency
string
Default: "EUR"

Name of currency

Value: "EUR"
amount
required
string

amount for iban fee

iban
string

IBAN for withdraw

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400003: Currency is not supported;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;
* 403030: Service is unavailable for partner;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/fiat/withdraw-estimate-fee
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

User

/b2b/kyc/access-token

Get KYC access token for iframe

Securityb2b-bearer-token
Request
query Parameters
feature
required
string

KYC feature

Enum: "crypto" "iban"
Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400062: Cannot get KYC access token. Check the message field;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/kyc/access-token
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/kyc/documents

Get user’s previously uploaded KYC documents

Securityb2b-bearer-token
Responses
200

OK

400

Bad request

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/kyc/documents
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/contacts

Get user contacts

Securityb2b-bearer-token
Responses
200

OK

400

Error codes:
* 400064: User not found by token;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/contacts
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/dataDeprecated

B2B user data

Securityb2b-bearer-token
Responses
200

OK

400

Error codes:
* 400064: User not found by token;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/data
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/iban

Get user's IBAN

Securityb2b-bearer-token
Responses
200

OK

400

Error codes:
* 400000: risk error. Please contact support;
* 400049: IBAN not found;
* 400050: IBAN is not available for user;
* 400051: Gateway token expired. Please contact support;
* 400056: IBAN already exists;
* 400066: Unknown error;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

Error codes:
* 500000: Check IBAN available error in risk. Please contact support;

get/b2b/user/iban
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/iban

Create IBAN

Securityb2b-bearer-token
Responses
200

OK

400

Error codes:
* 400000: risk error. Please contact support;
* 400049: IBAN not found;
* 400050: IBAN is not available for user;
* 400051: Gateway token expired. Please contact support;
* 400056: IBAN already exists;
* 400066: Unknown error;

401

401000: Authorization failed

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

Error codes:
* 500000: Check IBAN available error in risk. Please contact support;

post/b2b/user/iban
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/iban-limits/buy

Get IBAN limits for buy operations

Securityb2b-bearer-token
Request
query Parameters
crypto_currency
required
string

Crypto currency to buy

fiat_currency
required
string

Fiat currency to buy with

payment_method
required
string

Selected payment method

Enum: "iban_exchange" "iban_invoice"
Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400003: Currency is not supported;
* 400060: Fail to get IBAN limits. Check the message field;
* 400066: Unknown error;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/iban-limits/buy
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/iban-limits/deposit

Get IBAN limits for deposit operations

Securityb2b-bearer-token
Request
query Parameters
fiat_currency
required
string

Fiat currency to deposit

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400003: Currency is not supported;
* 400060: Fail to get IBAN limits. Check the message field;
* 400066: Unknown error;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/iban-limits/deposit
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/iban-limits/sell

Get IBAN limits for sell operations

Securityb2b-bearer-token
Request
query Parameters
crypto_currency
required
string

Crypto currency to sell

fiat_currency
required
string

Fiat currency to sell to

payment_method
required
string

Selected payment method

Enum: "iban_exchange" "iban"
Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400003: Currency is not supported;
* 400060: Fail to get IBAN limits. Check the message field;
* 400066: Unknown error;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/iban-limits/sell
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/iban-limits/withdraw

Get IBAN limits for withdraw operations

Securityb2b-bearer-token
Request
query Parameters
fiat_currency
required
string

Fiat currency to withdraw

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400003: Currency is not supported;
* 400060: Fail to get IBAN limits. Check the message field;
* 400066: Unknown error;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/iban-limits/withdraw
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/kyc-access-token

Get KYC access token for iframe

Securityb2b-bearer-token
Request
query Parameters
kyc_level
integer
Default: "1"

Level of kyc

Enum: 1 2
Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400062: Cannot get KYC access token. Check the message field;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/kyc-access-token
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/kyc-documentsDeprecated

Get user’s previously uploaded KYC documents

Securityb2b-bearer-token
Responses
200

OK

400

Bad request

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/kyc-documents
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/kyc-documents

Send user’s KYC documents

Securityb2b-bearer-token
Request
Request Body schema: application/json
required

JSON Body

address_1
string

Address 1 line (required, only for US kyc level1)

address_2
string

Address 2 line (required, only for US kyc level1)

birthday
string

Birthday. Format '1995-05-25'. (required, only for kyc level1)

citizenship_country_code
string

user's country (required, only for kyc level2 without verification)

city
string

City (required, only for US kyc level1)

correspondence_address_line
string

User's coresponcence address line (required, only for kyc level2 without verification)

correspondence_city
string

User's coresponcence city (required, only for kyc level2 without verification)

correspondence_country_code
string

User's coresponcence country code (required, only for kyc level2 without verification)

correspondence_postal_code
string

User's coresponcence postal code (required, only for kyc level2 without verification)

correspondence_state
string

User's coresponcence state (required, only for kyc level2 without verification)

country_code
string

Country code (required, only for kyc level1)

required
Array of objects
first_name
string

First name (required, only for kyc level1)

first_name_en
string

First name (required, only for kyc level1)

id_number
string

US ID number (required, only for US kyc level1)

kyc_level
integer
Default: "1"

Level of kyc documents

Enum: 1 2
last_name
string

Last name (required, only for kyc level1)

last_name_en
string

Last name (required, only for kyc level1)

residence_address_line
string

user's address line (required, only for kyc level2 without verification)

residence_city
string

user's city (required, only for kyc level2 without verification)

residence_country_code
string

user's country (required, only for kyc level2 without verification)

residence_postal_code
string

User's residence postal code (required, only for kyc level2 without verification)

residence_state
string

User's residence country code (required, only for kyc level2 without verification)

state
string

State code (required, only for US kyc level1)

zip
string

ZIP code (required, only for US kyc level1)

Responses
200

OK

400

Error codes:
* 400000: Bad request;
* 400001: Validation error, check the data field;
* 400005: Validation error for country_code field;
* 400039: Validation error for document field;
* 400040: Validation error for birthday field;
* 400041: Validation error for first_name field;
* 400042: Validation error for last_name field;
* 400066: Unknown error;
* 400067: User profile save error;

401

401000: Authorization failed

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403022: KYC already complete;
* 403023: Various reasons, check the message field;
* 403030: This endpoint is disabled for current partner;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/user/kyc-documents
Request samples
application/json
{
  • "address_1": "Plaza Dr",
  • "address_2": "1609",
  • "birthday": "1995-05-25",
  • "citizenship_country_code": "us",
  • "city": "Woodbridge",
  • "correspondence_address_line": "Gebbertstraße, 123",
  • "correspondence_city": "Erlangen",
  • "correspondence_country_code": "de",
  • "correspondence_postal_code": "91058",
  • "correspondence_state": "Bayern",
  • "country_code": "pl",
  • "document": [
    ],
  • "first_name": "Adam",
  • "first_name_en": "Adam",
  • "id_number": "123456789",
  • "kyc_level": "1",
  • "last_name": "Smith",
  • "last_name_en": "Smith",
  • "residence_address_line": "string",
  • "residence_city": "string",
  • "residence_country_code": "us",
  • "residence_postal_code": "91058",
  • "residence_state": "string",
  • "state": "NJ",
  • "zip": "07095"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "202"
}

/b2b/user/kyc-share-token

Send share-token for KYC

Securityb2b-bearer-token
Request
Request Body schema: application/json
required

JSON Body

kyc_level
integer
Default: "1"

Level of kyc

Enum: 1 2
share_token
required
string

share_token

Responses
200

OK

400

Error codes:
* 400001: Validation error, check the data field;
* 400064: User not found by token and user_uuid4;

401

401000: Authorization failed

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403022: KYC already complete;
* 403023: Applicant already exists;
* 403026: Resource is unavailable. Please contact support;
* 403030: This endpoint is disabled for current partner;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/user/kyc-share-token
Request samples
application/json
{
  • "kyc_level": "1",
  • "share_token": "_act-75e78843-3207-4be6-asdb936-9842ae2a0c71"
}
Response samples
application/json
{
  • "data": { },
  • "status": "202"
}

/b2b/user/kyc-status

Get user KYC statuses

Securityb2b-bearer-token
Responses
200

OK

400

Error codes:
* 400064: User not found by token;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/kyc-status
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/refresh-token

Refresh b2b-bearer-token

Securityb2b-bearer-token
Responses
200

OK

400

Error codes:
* 400014: Empty widget error. Contact your account manager;
* 400064: User not found by token;

401

401000: Authorization failed

403

Error codes:
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

get/b2b/user/refresh-token
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/set-phone

Set user phone

Securityb2b-bearer-token
Request
Request Body schema: application/json
required

New user phone

phone
required
string

New user phone

Responses
200

OK

400

Error codes:
* 400073: Validation error for the phone field;

401

401000: Authorization failed

403

Error codes:
* 403003: Too many requests for phone validation;
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403026: Resource is unavailable. Please contact support;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/user/set-phone
Request samples
application/json
{
  • "phone": "string"
}
Response samples
application/json
{
  • "data": [
    ],
  • "status": "200"
}

/b2b/user/sign-in

Sign-in user

Securitysdk-partner-token
Request
Request Body schema: application/json
required

JSON Body

email
string

email

phone
string

Phone

user_uuid4
string

uuid4

Responses
200

OK

400

Error codes:
* 400004: Validation error for user_uuid4 field;
* 400010: Validation error for phone field;
* 400014: Empty widget error. Contact your account manager;
* 400037: Validation error for email field;
* 400063: Requires one of the parameters: phone, user_uuid4, email;

401

401000: Authorization failed

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403031: User is locked by some reason or not found;
* 403031: User email is not confirmed;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/user/sign-in
Request samples
application/json
{
  • "email": "someemail@gmail.com",
  • "phone": "+35797522499",
  • "user_uuid4": "69f63545-9a58-4075-894d-47490eeed55b"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}

/b2b/user/sign-up

Sign-up user

Securitysdk-partner-token
Request
Request Body schema: application/json
required

JSON Body

accept
required
boolean

accept

email
required
string

email

Responses
200

OK

400

Error codes:
* 400006: You need to accept the user agreement to signup;
* 400014: Empty widget error. Contact your account manager;
* 400037: Validation error for email field;

401

401000: Authorization failed

403

Error codes:
* 403007: There's another active transaction;
* 403020: IP is blacklisted;
* 403023: Sign-up failed. Check the message field;

405

405000: Method Not Allowed

500

500001: Various reasons, check the message field

post/b2b/user/sign-up
Request samples
application/json
{
  • "accept": "true",
  • "email": "someemail@gmail.com"
}
Response samples
application/json
{
  • "data": {
    },
  • "status": "200"
}