Mercuryo Spend Card API is a solution which allows to issue a Mercuryo virtual payment card for end-user. Once the Spend card is issued, it can be used when selling crypto for fiat money and withdrawing funds, as well as in POS and e-commerce transactions.

Before using the Sandbox environment, prepare these:

• IP addresses to add to the whitelist.
• An e-mail address to log in.

The Sandbox environment works with the following networks:

Contact your integration manager. You will get the Sdk-Partner-Token to sign up user registration and authorization endpoints to access API.

All the requests must contain:

• Content-Type: application/json
• Accept: application/json

Sandbox URL

• API Host https://sandbox-api.mrcr.io.

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

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

• Sdk-User-Token - a token received as a result of sign-in process and used for all user-specific requrests.

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

Spend Cards API endpoints accept the B2B-User-Ip header, and it is mandatory when Sdk-User-Token is used for authorization. It must contain the real IP address of end-user.

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

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

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

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

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

This scenario assumes that a merchant validates user's e-mail and identity, and no additional authentication is required to access Spend Card API.

Steps

1. Ask your integration manager for the Sdk-Partner-Token, which is required for the following authentication endpoints.
2. Use POST /sdk-partner/user/sign-in-no-verify to sign-in a user without OTP e-mail verification.
3. Use GET /sdk-partner/user/refresh-token to refresh the Sdk-User-Token, if needed.

After user's successful authentication, 1) KYC verification and then 2) phone number specifying are required.

In the following scenario, a user must enter OTP submitted to their e-mail.

Steps

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

After user's successful authentication, 1) KYC verification and then 2) phone number specifying are required.

Steps

1. Use POST /sdk-partner/user/sign-out to sign-out a user.

Sdk-User-Token is deactivated. After signing out, authorization does not work with the same Sdk-User-Token.

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.

The list of required documents depends on the end-user's country of citizenship:

• European Economic Area (EEA), European Union (EU), United Kingdom (UK)*:
  • Passport with citizenship or ID card with citizenship.
  • Manual input of user address.
  • Liveness test (selfie).
• Switzerland and other countries where Mercuryo Off-ramp operations are allowed:
  • Passport with citizenship or ID card with citizenship.
  • Residence permit (accepted from EU countries only).
  • Proof of address (accepted from EU countries only).
  • Liveness test (selfie).

*- ID card is not accepted for UK citizens.

These documents can be acceptable identity verification:

• Passport.
• ID card.

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 two options of how KYC procedure can be implemented:

1. You request SumSub Access Token and redirect user to upload documents to SumSub portal.
2. If a user is verified by SumSub, you send us SumSub Share Token.

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

This KYC integration option is used to let a user upload documents for verification to SumSub directly.

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

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

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

Steps

1. Use GET /sdk-partner/user/kyc-status to get the KYC status. We can identify a user whom you registered by the e-mail if we already have it:
   1. If status is complete, then that’s it.
2. Use GET /sdk-partner/kyc/access-token to get the KYC access token.
3. Use a URL to redirect the user to Mercuryo.
   1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
   2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
   3. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
4. Once validation procedure is completed, SumSub will notify Mercuryo and user's KYC status will be updated. User will be notified by the email.
5. Use GET /sdk-partner/user/kyc-status to get the 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 open a Spend card. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the 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.

Steps

1. Use GET /sdk-partner/user/kyc-status to get the KYC status. We can identify a user whom you registered by the e-mail if we already have it:
   1. If status 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. Submit the share token using POST /sdk-partner/kyc/share-token.
4. Use GET /sdk-partner/user/kyc-status to get the 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 open a Spend card. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the documents.

OTP-less

This scenario assumes that a merchant validates user's phone number, and no additional validation is required.

Steps

1. Use POST /sdk-partner/user/set-phone-no-verify to submit user's phone number.

Opening a Spend card with an empty balance.

The end-user must 1) be signed in, 2) successfully complete KYC procedures (valid KYC), and 3) have a mobile phone number specified.

If something is not verified, you need to restart the authorization flow, or use GET /sdk-partner/user/contacts to check whether a user has a phone set. If needed, use GET /sdk-partner/user/kyc-status to check user’s verification. Please note that these endpoints are needed only if you want to check everything in advance before the transaction. You can try to open a card without doing these checks and focus on errors in the response of the POST /sdk-partner/spend/cards/open endpoint.

There can be only one Spend card per end-user (within all partners or within one partner depending on the pricing model).

Currently, only EUR can be used as currency.

Steps

1. Use POST /sdk-partner/spend/cards/open to open a Spend card with an empty balance.
   1. View the card_id parameter.
2. Use GET /sdk-partner/spend/cards/status to check the status of card. After opening, the card will be in the active status.
3. Use GET /sdk-partner/spend/cards/transactions to get the list of card transactions.
4. Use GET /sdk-partner/spend/cards/balance to get card balance.
5. You will have to use Mercuryo interface and integrate it via iFrame to acquire the unmasked card details. Get URL from POST /sdk-partner/spend/cards/iframe/init and display response of that URL in an iFrame.

Once the Mercuryo Spend card is issued, it can be used when selling crypto for fiat money and withdrawing funds, as well as in POS and e-commerce transactions.

Opening a Spend card with instant topup by selling crypto for fiat money.

The end-user must 1) be signed in, 2) successfully complete KYC procedures (valid KYC), and 3) have a mobile phone number specified.

If something is not verified, you need to restart the authorization flow, or use GET /sdk-partner/user/contacts to check whether a user has a phone set. If needed, use GET /sdk-partner/user/kyc-status to check user’s verification. Please note that these endpoints are needed only if you want to check everything in advance before the transaction. You can try to open a card without doing these checks and focus on errors in the response of the POST /sdk-partner/spend/cards/open-off-ramp endpoint.

There can be only one Spend card per end-user (within all partners or within one partner depending on the pricing model).

Currently, only EUR can be used as currency.

If needed, you can check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /sdk-partner/user/limits/spend, if you want to get limit details separately.

Steps

1. Use GET /sdk-partner/spend/cards/rates/open to get rates.
   1. The rates will be frozen and associated with the trx_token.
   2. Acquire rates again if the elapsed time is more than an hour, because trx_token expires in one hour.
2. Use POST /sdk-partner/spend/cards/open-off-ramp to start a transaction so that the user can confirm it and perform transfer in order to open a Spend card with instant topup.
   1. Mercuryo will create the sell request to confirm the transaction.
   2. Partner receives the address from Mercuryo.
   3. Partner asks the user to transfer the amount to the specified address.
   4. If the blockchain transaction is successfully completed, Mercuryo issues the card after receiving crypto.
3. Use GET /sdk-partner/spend/cards/sell-request/{id}/status to check the status of created sell request.
   1. Wait until the status of sell request changes to completed. Until then, the cryptocurrency is still being processed.
4. Use GET /sdk-partner/spend/cards/status to check the status of card.
5. Use GET /sdk-partner/spend/cards/transactions to get the list of card transactions.
6. Use GET /sdk-partner/spend/cards/balance to get card balance.
7. You will have to use Mercuryo interface and integrate it via iFrame to acquire the unmasked card details. Get URL from POST /sdk-partner/spend/cards/iframe/init and display response of that URL in an iFrame.

Once the Mercuryo Spend card is issued, it can be used when selling crypto for fiat money and withdrawing funds, as well as in POS and e-commerce transactions.

Replenishing a Spend card.

The end-user must 1) be signed in, 2) successfully complete KYC procedures (valid KYC), and 3) have a mobile phone number specified.

If needed, use GET /sdk-partner/user/kyc-status to check user’s verification. Please note that this endpoint is needed only if you want to check KYC status in advance before the transaction. You can try to topup a card without doing this check and focus on errors in the response of the POST /sdk-partner/spend/cards/crypto-topup endpoint.

If needed, you can check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use GET /sdk-partner/user/limits/spend, if you want to get limit details separately.

Steps

1. Use GET /sdk-partner/spend/cards/rates/crypto-topup to get rates.
   1. The rates will be frozen and associated with the trx_token.
   2. Acquire rates again if the elapsed time is more than an hour, because trx_token expires in one hour.
2. Use POST /sdk-partner/spend/cards/crypto-topup to replenish a Spend card.
   1. Mercuryo will create the sell request to confirm the transaction.
   2. Partner receives the address from Mercuryo.
   3. Partner asks the user to transfer the amount to the specified address.
   4. Mercuryo replenishes the card.
3. Use GET /sdk-partner/spend/cards/sell-request/{id}/status to check the status of created sell request.
   1. Wait until the status of sell request changes to completed. Until then, the cryptocurrency is still being processed.
4. Use GET /sdk-partner/spend/cards/transactions to get the list of card transactions.
5. Use GET /sdk-partner/spend/cards/balance to get card balance.

Viewing card's details.

Steps

1. Use GET /sdk-partner/spend/cards/status to check the status of card.
2. Use GET /sdk-partner/spend/cards/masked to get masked card data.
3. Use GET /sdk-partner/spend/cards/balance to get card balance.
4. Use GET /sdk-partner/spend/cards/transactions to get the list of card transactions.
5. You will have to use Mercuryo interface and integrate it via iFrame to acquire the unmasked card details. Get URL from POST /sdk-partner/spend/cards/iframe/init and display response of that URL in an iFrame.

Changing card's PIN code.

Steps

1. Use POST /sdk-partner/spend/cards/pin to change card's PIN code.

Freezing a card.

Steps

1. Use POST /sdk-partner/spend/cards/lock to lock the card.

When the card is locked, you can still perform the following actions: unlock the card, reissue a new card, and view the transaction history.

Unlocking a card.

Steps

1. Use POST /sdk-partner/spend/cards/unlock to unlock the card.

Once the card is unlocked, the funds will be transferred to it.

Replacing the card with a new one.

To reissue a card, you must first block the current card. The remaining balance on the blocked card will be saved and transferred to a new card. The new card will have different card details from the blocked one.

Steps

1. Use POST /sdk-partner/spend/cards/replace to replace the card with a new one.

Mercuryo sends callbacks when the transaction status changes. Set up a callback URL to receive callbacks.

Steps

1. Sign in the Dashboard.
2. Go to Widgets.
3. Select a widget.
4. Fill in the field Callback URL.

Go to Widget Callbacks to browse callbacks, resend a callback, and send a test callback.

Callback Body

{
   "data":{
      "id":"0ab3f70c72c0f5056",
      "fee":"11.80",
      "card":{
         "number":"1111"
      },
      "rate":"25756.99",
      "type":"buy",
      "user":{
         "email":"sf@mercuryo.io",
         "phone":"+3570000000",
         "uuid4":"b5086805-4b83-4415-8a00-5c1ad43210b6",
         "country_code":"de"
      },
      "amount":"0.00148310",
      "status":"paid",
      "currency":"BTC",
      "created_at":"2023-09-07 07:32:33",
      "updated_at":"2023-09-07 07:32:46",
      "fiat_amount":"50.00",
      "partner_fee":"0.00",
      "created_at_ts":1694071953,
      "fiat_currency":"USD",
      "updated_at_ts":1694071966,
      "payment_method":"card",
      "card_masked_pan":null,
      "merchant_transaction_id":"123"
   }
}

The sign key is used for checking the callback signature. When the transaction status changes, the merchant receives a request with transaction data from Mercuryo. If you use callbacks, you can set up the signature check.

You can check the signature by generating a hash with the HMAC sha256 algorithm and a key from the Sign Key field in the Dashboard. Check the X-Signature HTTP header against the generated hash.

Visit Help Center

What happens if an end-user who has already completed KYC wants to re-register with a new email address and redo KYC?

Re-registering a new email address is only possible through our Customer Support. If the user logs in with the new email and attempts to complete KYC, an error will occur indicating that the user is already registered and must use the old account. The error code 403082: KYC is already completed will be returned by the GET /sdk-partner/user/kyc-status endpoint.

Are ATM withdrawals possible?

No, ATM withdrawals are not possible.

What are the limits of the Spend card? Are these limits adjustable by a user?

Please see the limites here. No, there are no limits adjustable by a user.

When a user sends their funds, will this transaction appear on the list of transactions before it is fully settled and the card balance is updated?

No, the transaction will only be visible after the funds have been credited to the card.

Can users initiate multiple top-up transactions in succession?

Users can initiate multiple top-up transactions in succession, provided each transaction involves different amounts and/or different cryptocurrencies or networks. However, if a user attempts to send the same amount of funds in the same cryptocurrency at the same time, it may cause issues with transfer.