Spend API

About

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.

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 0xbBC8f6B710359dbcdF02f9eb50Ade391890A6021 Ethereum (ETH) and USDT

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

Security

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.

Sign-Up and Sign-In

For authentication of new and existing users, the same API and authorization processes are used. In case when a user with specified email 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 email is used as an identifier. Please check with your integration manager which scenario you can use.

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

OTP-less Sign-In

This scenario assumes that a merchant validates user's email 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 email 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.

Sign-In with OTP Verification

In the following scenario, a user must enter OTP submitted to their email.

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.

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

Sign-Out

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.

KYC

Know Your Customer (KYC) procedures are indispensable for financial institutions to verify their clients and keep business on the safe side.

KYC procedures help Mercuryo fight financial crime. Therefore, it prevents mixing your users’ funds with illegal funds of bad actors and perpetrators of any sort. Identity verification is a legal obligation to be compliant with AML/CFT laws. Mercuryo is strongly committed to the highest industry standards of clients' security, which requires protecting the integrity of the entire financial system.

SumSub is the major KYC procedure provider of Mercuryo.

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

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

Identity Verification

These documents can be acceptable identity verification:

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

The document must have:

  • Full name.
  • MRZ code.
  • Citizenship.
  • Date of birth.
  • Document number.
  • Issuing authority.
  • Date of issue.

Meet these requirements:

  • The document must be unexpired.
  • The document must be scanned or photographed.
  • All the corners and sides of the document must be visible.
  • All the information must be clear and readable.

Proof of Address

We do not accept bank statements from neobanks.

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

SumSub Access Token

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.

Parameter Description Type
access_token Get the access token using GET /sdk-partner/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 /sdk-partner/user/kyc-status to get the KYC status. We can identify a user whom you registered by the email if we already have it:
    1. If in the list of features, the necessary feature 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. If in Sandbox mode, you don't want to wait for us to manually confirm the KYC review, use the test documents for which automatic processing is set up on the SumSub's side: Verification Document Templates.
  4. 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 for the necessary feature.
    1. Statuses:
      1. complete: KYC procedures are successfully complete.
      2. incomplete: not enough documents have been provided; SumSub hasn’t started the verification.
      3. failed_attempt: the first attempt to pass the verification failed. Try again.
      4. failed: the verification failed; the user isn’t allowed to open a Spend card. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the documents. Appears only after the user has finished uploading and submitting all required documents and the verification process has started on SumSub’s side.
    2. If the KYC status is incomplete or failed_attempt, re-take KYC.
      1. Use GET /sdk-partner/kyc/access-token to get the KYC access token.
      2. Use a URL to redirect the user to Mercuryo.
        1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
        2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
        3. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
        4. If in Sandbox mode, you don't want to wait for us to manually confirm the KYC review, use the test documents for which automatic processing is set up on the SumSub's side: Verification Document Templates.
  6. When a user’s document expires, you can send them a new SumSub link (using the GET /sdk-partner/kyc/access-token endpoint) so they can re-upload their document. However, this is optional — card support is not suspended when documents expire. The document just needs to be valid at the time it was originally submitted.

SumSub Share Token

If you have already integrated SumSub KYC procedures, you can share your SumSub applicants with Mercuryo using the share token. The SumSub share token is used by Mercuryo to share applicants and complete the KYC procedures. So, the users won’t have to do the verification twice. See how it works.

Make sure that your applicant’s documents are up-to-date before sharing an applicant using the share token. Mercuryo can accept the share token only once due to the SumSub architecture.

The Sandbox environment requires approving users manually. If in Sandbox mode, you don't want to wait for us to manually confirm the KYC review, use the test documents for which automatic processing is set up on the SumSub's side: Verification Document Templates.

Share Token Processing Rules

When using the SumSub share token, the following rules apply:

  1. Field mapping

    • Field sets may differ between systems. Field extraction is not based on field matching.
    • Only document types and allowed countries are considered during the matching process.

  2. Minimum requirement

    • The applicant must have completed at least:
      • Identity verification (ID document)
      • Liveness check (selfie)
    • The applicant must have an approved ("green") status on your side.
    • Additional verification steps are allowed, but only ID and Selfie are reused.

  3. Import behavior

    • If the minimum requirement is met, the applicant will be successfully imported.
    • Field differences and additional steps do not affect the import result.

  4. Matching logic

    • The share token flow is triggered by an email match.
    • Once matched, the applicant is imported based on ID and Selfie verification.

Partner Requirements

To use the share token flow, you must:

  • Provide the user's email, as it is used to match the applicant during the share token flow
  • Ensure the applicant has completed ID + Selfie verification
  • Include the share token in the request

Whitelisting Prerequisite

Before you can use the share token, you must complete the whitelisting process with SumSub and Mercuryo. If you skip these steps, you will not be able to use the share token.

  1. Conclude a contract with SumSub for the Reusable KYC feature.
  2. Request a partner token from your Mercuryo integration manager.
  3. Add the received partner token in SumSub.
    1. Log in to your SumSub account.
    2. Go to the Partners → Recipients tab.
    3. Click Add Recipient and enter the partner token.
  4. Ask your Mercuryo manager to verify the setup.

Steps

  1. Use GET /sdk-partner/user/kyc-status to get the KYC status. We can identify a user whom you registered by the email if we already have it:
    1. If in the list of features, the necessary feature 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. The response will include an access_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: not enough documents have been provided; SumSub hasn’t started the verification.
      3. failed_attempt: the first attempt to pass the verification failed. Try again.
      4. failed: the verification failed; the user isn’t allowed to open a Spend card. Contact Mercuryo Support.
      5. under_review: SumSub is verifying the documents. Appears only after the user has finished uploading and submitting all required documents and the verification process has started on SumSub’s side.
    2. If the KYC status is incomplete or failed_attempt, re-take KYC.
      1. Use the received access_token to redirect the user to the SumSub interface in order to provide additional information during the verification process.
      2. Use a URL to redirect the user to Mercuryo.
        1. The Production environment URL example: https://payments.mercuryo.io/kyc?access_token=your_token8&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
        2. The Sandbox environment URL example: https://sandbox-payments.mrcr.io/kyc?access_token=your_token&success_url=url&failure_url=url&scheme=your_scheme&lang=lang_code.
          1. When testing KYC procedures for Sandbox, upload the documents and contact Mercuryo to approve the documents.
          2. If in Sandbox mode, you don't want to wait for us to manually confirm the KYC review, use the test documents for which automatic processing is set up on the SumSub's side: Verification Document Templates.

Phone Number Specifying

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.

Questionnaire

The platform may require end users to complete one or more questionnaires as part of verification or product activation (for example, SPEND_EEA before opening a Spend card).

When a questionnaire is required

  • You will be informed that a questionnaire is required by the platform’s public API responses when attempting an operation (for example, opening a Spend card). If an operation fails with an error indicating a questionnaire is required, present the appropriate questionnaire to the end user and submit it as described below.
  • For the Spend card flow, SPEND_EEA must be submitted before calling POST /sdk-partner/spend/cards/open. If SPEND_EEA is not completed, the API may return error 403106. See the Appendix: SPEND_EEA Questionnaire Fields for the full list of enum options and human-readable labels.
  • If a user who already completed KYC attempts to re-register with a different email, the API may return 403082: KYC is already completed. Handle that case according to your UX (for example, show guidance to contact support).

How to submit a questionnaire

  1. Present the questionnaire form to the end user. Use the Appendix: SPEND_EEA Questionnaire Fields for the full list of enum options and human-readable labels.
  2. Submit the completed questionnaire to the public questionnaire endpoint: POST /sdk-partner/questionnaire/spend-eea.
  3. OTHER option rule: If any enum field value is OTHER, you must include the corresponding other_* text field in the request. Examples: other_purpose_of_wallet_usage, other_employment_status, other_occupation, other_source_of_funds, etc.
  4. After successful questionnaire submission, retry the original operation (for example, open the card).

Scenarios

Spend Card Open

Opening a Spend card with an empty balance.

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

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/questionnaire/spend-eea to submit the SPEND_EEA questionnaire before opening the Spend card. This questionnaire collects information about the user's employment status, income, source of funds and intended card usage for compliance purposes.
    1. Ensure the user has completed KYC verification for the card feature. If not, the endpoint will return error 400251 with next: "verify-kyc".
    2. The endpoint accepts a payload compliant to the static contract with predefined enum values. Fields with an OTHER option require additional other_* fields to be filled.
    3. See the Appendix: SPEND_EEA Questionnaire Fields for the full list of enum options and human-readable labels.
  2. Use POST /sdk-partner/spend/cards/open to open a Spend card with an empty balance.
    1. View the card_id parameter.
    2. If the user has not completed the SPEND_EEA questionnaire, the error 403106 will be returned. The user must complete the questionnaire first using POST /sdk-partner/questionnaire/spend-eea.
  3. Use GET /sdk-partner/spend/cards/status to check the status of card. Mercuryo initially issues the card with a new status. Once the user has been verified by the vendor, a callback is triggered to update the card’s status to active. It’s important to distinguish between KYC verification and vendor verification: after a user completes KYC, we send their documents to the vendor for verification, but the vendor may still reject them.
  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.
  6. 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.

Spend Card Open Off-Ramp

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

Note: This scenario is currently unavailable.

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 in the new status after receiving crypto. Moments later, a callback will update the card’s status to active.
  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.
    2. The response may include a failed_reason field indicating the reason for failure (e.g., spend_cards_limits_error when the card has reached its top-up limit).
  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.

Spend Card Top-Up

Replenishing a Spend card.

Replenishing a card without an open card is not possible. The end-user must have an open card before replenishing it.

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 the latest active card. For a specific card, use POST /sdk-partner/spend/cards/{card_id}/crypto-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. 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.
    2. The response may include a failed_reason field indicating the reason for failure (e.g., spend_cards_limits_error when the card has reached its top-up limit).
  4. Use GET /sdk-partner/spend/cards/transactions to get the list of transactions for the latest active card. For a specific card, use GET /sdk-partner/spend/cards/{card_id}/transactions.
  5. Use GET /sdk-partner/spend/cards/balance to get the latest active card balance. For a specific card, use GET /sdk-partner/spend/cards/{card_id}/balance.

Spend Card Details

Viewing card's details.

Steps

  1. Use GET /sdk-partner/spend/cards/status to check the status of the latest active card. For a specific card, use GET /sdk-partner/spend/cards/{card_id}/status.
  2. Use GET /sdk-partner/spend/cards/masked to get masked card data for the latest active card.
  3. Use GET /sdk-partner/spend/cards/balance to get the latest active card balance. For a specific card, use GET /sdk-partner/spend/cards/{card_id}/balance.
  4. Use GET /sdk-partner/spend/cards/transactions to get the list of transactions for the latest active card. For a specific card, use GET /sdk-partner/spend/cards/{card_id}/transactions.
  5. Use Mercuryo interface and integrate it via iFrame to acquire the unmasked card details for the latest active card. Get the URL from POST /sdk-partner/spend/cards/iframe/init and display the response in an iFrame.

Spend Card Pin

Setting or updating card's PIN code.

Steps

  1. Use POST /sdk-partner/spend/cards/{card_id}/pin to set or update the PIN code for a specific card.

Spend Card Lock

Freezing a card.

Steps

  1. Use POST /sdk-partner/spend/cards/lock to lock the latest active card.
  2. To lock a specific card, use POST /sdk-partner/spend/cards/{card_id}/lock.

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

Spend Card Unlock

Unlocking a card.

Steps

  1. Use POST /sdk-partner/spend/cards/unlock to unlock the latest active card.
  2. To unlock a specific card, use POST /sdk-partner/spend/cards/{card_id}/unlock.

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

Spend Card Replace

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 latest active card.
  2. To replace a specific card, use POST /sdk-partner/spend/cards/{card_id}/replace.

Callbacks

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 Callback URL field.

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

Spend Card Events

Mercuryo sends callbacks for Spend card events:

  • When the card status changes.
  • When the card is replenished with crypto.
  • For the card transactions.

To set up a callback URL to receive callbacks for Spend card events, contact your integration manager.

Callback Body: Spend Card Status Change 

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8", // unique event identifier, the same for all retries of the same event
  "event_name": "card_status", 
  "card_id": "0c379cbae24f62922", 
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66", 
  }
  "status": "active", 
  "created_at": "2024-06-27 08:26:35", 
  "updated_at": "2024-06-27 08:26:41", 
}

If the callback service returns a 500 error, the system will retry the request using exponential backoff, up to a maximum of 10 attempts.

Callback Body: Replenishing Spend Card with Crypto 

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "crypto_top_up",
  "card_id": "0c379cbae24f62922", 
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66" 
  },
  "sell_request": {
    "id": "0daa380ba39596745", 
    "merchant_transaction_id": "00357ec76de855485", 
    "status": "new|pending|succeeded|failed", 
    "fiat_amount": "130.34", 
    "fiat_currency": "EUR", 
    "fee": "2", 
    "crypto_amount": "0.02", 
    "crypto_currency": "BTC" 
  },
  "refund_address": "0xc83935B7295FEC64E32B62C33C24dFdfE04092A9", 
  "address": "0xc83935B7295FEC64E32B62C33C24dFdfE04092A9", 
  "sender_address": ["0xc83935B7295FEC64E32B62C33C24dFdfE04092A9"], 
  "card_balance": "130|null", 
  "created_at": "2024-06-27 08:26:35", 
  "updated_at": "2024-06-27 08:26:41" 
}

Callback Body: Spend Card Transactions 

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "card_transaction",
  "card_id": "0c379cbae24f62922", 
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66" 
  },
  "transaction": {
    "id": "0daa380ba39596745",
    "type": "PURCHASE",
    "status":"AUTHORIZED|CLEARED|DECLINED|REVERSED|INVALID",
    "decline_reason": null|"",
    "local_amount":"123", 
    "local_currency":"EUR",
    "amount": "123",
    "currency": "EUR",
    "fx_rate": null,
    "mcc": "288",
    "counterparty_name": "Some Name"
  },
  "created_at": "2024-06-27 08:26:35",
  "updated_at": "2024-06-27 08:26:41"
}

Callback Signature

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.

Appendix: SPEND_EEA Questionnaire Fields

All enum keys are case-sensitive and must match the API contract. Do not send custom values beyond the enums.

Note on selection type: Multi-select is not supported. Each enum field accepts a single enum value (a single string), not an array. If more than one option applies, choose the value that best represents the primary purpose. If none of the predefined values fits, set the enum to OTHER and provide a descriptive value in the corresponding other_* field.

If an enum field contains an OTHER option, the corresponding other_* text field must be provided. Example:

  "purpose_of_wallet_usage": "OTHER",
  "other_purpose_of_wallet_usage": "Collecting payments for a private nonprofit"

purpose_of_wallet_usage / other_purpose_of_wallet_usage

Enum Label
PERSONAL_SPENDING Personal spending
ONLINE_SHOPPING Online shopping
SUBSCRIPTIONS_SERVICES Subscriptions / services
FAMILY_FRIENDS Family / friends
SALARY_INCOME Salary / income
SAVINGS Savings
INVESTMENTS_TRADING Investments / trading
BILL_PAYMENTS Bill payments
TRAVEL_EXPENSES Travel expenses
GAMING_BETTING Gaming / betting
OTHER Other — provide other_purpose_of_wallet_usage

other_purpose_of_wallet_usage — free-text, required when purpose_of_wallet_usage = OTHER.

employment_status / other_employment_status

Enum Label
PRIVATE_EMPLOYEE Private employee
GOVERNMENT_EMPLOYEE Government employee
SELF_EMPLOYED Self-employed
BUSINESS_OWNER Business owner
STUDENT Student
RETIRED Retired
UNEMPLOYED Unemployed
OTHER Other — provide other_employment_status

other_employment_status — free-text, required when employment_status = OTHER.

occupation_position

Enum Label
MANAGER Manager
PROFESSIONAL Professional
TECHNICIAN_ASSOCIATE Technician / Associate
CLERICAL_SUPPORT Clerical support
SERVICE_SALES Service / Sales
AGRICULTURAL_FORESTRY_FISHERY Agricultural / Forestry / Fishery
CRAFT_TRADES Craft trades
MACHINE_OPERATOR Machine operator
ELEMENTARY Elementary
NOT_APPLICABLE Not applicable

occupation

Enum Label
ACCOUNTING_AUDIT Accounting / Audit
PAYMENTS_EMONEY Payments / e-money
CURRENCY_EXCHANGE Currency exchange
BANKING_LENDING Banking / Lending
CONSULTANCY_LEGAL Consultancy / Legal
PUBLIC_ADMINISTRATION Public administration
HEALTH_CARE_MEDICAL Health care / Medical
EDUCATION Education
INFORMATIONAL_TECHNOLOGIES Information technologies
CONSTRUCTION_REPAIR Construction / Repair
REAL_ESTATE Real estate
MANUFACTURING Manufacturing
PR_MARKETING PR / Marketing
TRADE_FOOD_PRODUCTS Trade — food products
WHOLESALE Wholesale
REPAIR_MOTOR_VEHICLES Motor vehicle repair
TRANSPORTATION_LOGISTICS Transport / Logistics
COURIER_POST Courier / Post
HOSPITALITY_LEISURE Hospitality / Leisure
SOCIAL_WORK Social work
FREELANCE Freelance
ADMINISTRATIVE_OFFICE Administrative office
OTHER_TRADE_SALES Other trade / sales
INVESTMENTS_TRADING Investments / Trading
SECURITIES_TRADING_OTC Securities trading (OTC)
HIGH_VALUE_ASSETS High-value assets
CRYPTOCURRENCIES Cryptocurrencies
PRECIOUS_METALS_STONES Precious metals / stones
PAWNSHOPS Pawnbrokers
CROSS_BORDER_CASH_METALS Cross-border cash & metals
MINING_EXTRACTIVE Mining / extractive
ENERGY Energy
TRADE_PETROL Trade — petrol
TRADE_MEDICINES Trade — medicines
NON_PROFIT_ENTITIES Non-profit entities
GAMING_ONLINE Gaming — online
GAMBLING_ONLINE Gambling — online
EU_FUNDS EU funds
ADULT Adult industry
INSURANCE_SECURITY Insurance / Security
UTILITIES_INFRASTRUCTURE Utilities / Infrastructure
AUTO_AVIATION Auto / Aviation
AGRICULTURE_FORESTRY Agriculture / Forestry
TRAVEL_TOURISM Travel / Tourism
INFORMATION_COMMUNICATION Information & Communication
ART_ENTERTAINMENT_SPORT Art / Entertainment / Sport
SCIENTIFIC_TECHNICAL Scientific / Technical
OTHER Other — provide other_occupation

other_occupation — free-text, required when occupation = OTHER.

client_monthly_net_income

Enum Label
LESS_THAN_1000_EUR < €1,000
BETWEEN_1001_AND_5000_EUR €1,001–€5,000
BETWEEN_5001_AND_10000_EUR €5,001–€10,000
BETWEEN_10001_AND_15000_EUR €10,001–€15,000
MORE_THAN_15000_EUR > €15,000

type_of_incoming_funds

Enum Label
DOMESTIC Domestic
INTRA_EU_EEA Within EU / EEA
CROSS_BORDER Cross-border (outside EU / EEA)

expected_incoming_monthly_eur / expected_outgoing_monthly_eur

Enum Label
LESS_THAN_1000_EUR < €1,000
BETWEEN_1001_AND_5000_EUR €1,001–€5,000
BETWEEN_5001_AND_10000_EUR €5,001–€10,000
BETWEEN_10001_AND_15000_EUR €10,001–€15,000
MORE_THAN_15000_EUR > €15,000

expected_monthly_frequency_incoming_transfer

Enum Label
LESS_THAN_2_TIMES < 2 times / month
BETWEEN_3_5_TIMES 3–5 times / month
MORE_THAN_6_TIMES > 6 times / month

source_of_funds

Enum Label
PERSONAL_SAVINGS Personal savings
FAMILY_SAVINGS Family savings
LABOR_CONTRACT Labor contract
CIVIL_CONTRACT Civil contract
DIVIDENDS Dividends
INHERITANCE Inheritance
LOAN_FINANCIAL_INSTITUTION Loan — financial institution
LOAN_NON_FINANCIAL Loan — non-financial
ORDINARY_BUSINESS_ACTIVITY Ordinary business activity
RENT Rent
SALE_COMPANY_SHARES Sale — company shares
SALE_MOVABLE_ASSETS Sale — movable assets
SALE_REAL_ESTATE Sale — real estate
SALE_FINANCIAL_INSTRUMENTS Sale — financial instruments
SALE_SERVICES Sale — services
SALE_CRYPTOCURRENCIES Sale — cryptocurrencies
SALE_IP_RIGHTS Sale — IP rights
FREELANCER_INCOMES Freelancer incomes
INVESTMENTS_FUNDS Investment funds
COPYRIGHT_LICENSES Copyright / license
GAMBLING_WINNINGS Gambling winnings
INTEREST_REVENUE Interest revenue
PENSIONS_SOCIAL_ASSISTANCE Pensions / social assistance
OTHER Other — provide other_source_of_funds

other_source_of_funds — free-text, required when source_of_funds = OTHER.

Questionnaire UI Example (JSON)

Below is an example of the questionnaire definition used by the UI (the "spend_questions_eea" payload).

Note: the UI option values in this JSON are lower_snake_case (for example "personal_spending"). The API enums in this Appendix are UPPER_SNAKE_CASE (for example PERSONAL_SPENDING). When sending data to the API, use the API enum keys as described above — map UI values to API enum keys if necessary (or use the server-side mapping implemented by the backend).

{
  "id": "spend_questions_eea",
  "title": "A few questions before we continue",
  "localizedTitle": {
    "values": [
      {
        "lang": "en",
        "value": "A few questions before we continue"
      }
    ]
  },
  "desc": "We will ask a few quick questions to make sure your card works as expected.",
  "localizedDesc": {
    "values": [
      {
        "lang": "en",
        "value": "We will ask a few quick questions to make sure your card works as expected."
      }
    ]
  },
  "modifiable": true,
  "sections": [
    {
      "id": "purposeOfWalletUsage",
      "title": "How do you plan to use your card?",
      "localizedTitle": {
        "values": [
          {
            "lang": "en",
            "value": "How do you plan to use your card?"
          }
        ]
      },
      "desc": "We use this to make sure everything works smoothly for you.",
      "localizedDesc": {
        "values": [
          {
            "lang": "en",
            "value": "We use this to make sure everything works smoothly for you."
          }
        ]
      },
      "condition": null,
      "showCondition": null,
      "items": [
        {
          "id": "purpose_of_wallet_usage",
          "title": "",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "select",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "personal_spending",
              "title": "Personal spending",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Personal spending"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "online_shopping",
              "title": "Online shopping",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Online shopping"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "paying_for_subscription",
              "title": "Paying for subscriptions/services",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Paying for subscriptions/services"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "sending_money_to_family",
              "title": "Sending money to family/friends",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Sending money to family/friends"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "receiving_salary",
              "title": "Receiving salary/income",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Receiving salary/income"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "savings_funds",
              "title": "Savings",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Savings"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "investments_trading",
              "title": "Investments/Trading",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Investments/Trading"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "bill_payments",
              "title": "Bill payments (utilities, rent, etc.)",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Bill payments (utilities, rent, etc.)"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "travel_expenses",
              "title": "Travel expenses (flights, hotels, etc.)",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Travel expenses (flights, hotels, etc.)"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "online_gaming",
              "title": "Online gaming or betting",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Online gaming or betting"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "other",
              "title": "Other",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Other"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "other_purpose_of_wallet_usage",
          "title": "Please describe how you will use the card",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "Please describe how you will use the card"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "text",
          "required": true,
          "format": null,
          "condition": "purposeOfWalletUsage.purpose_of_wallet_usage = other",
          "showCondition": null,
          "placeholder": "Add details",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": "Add details"
              }
            ]
          },
          "options": null,
          "arbitraryDocType": null
        }
      ],
      "delimiter": null,
      "useRandomItems": null,
      "randomItemsCount": null
    },
    {
      "id": null,
      "title": null,
      "localizedTitle": {
        "values": [
          {
            "lang": "en",
            "value": ""
          }
        ]
      },
      "desc": null,
      "localizedDesc": {
        "values": [
          {
            "lang": "en",
            "value": ""
          }
        ]
      },
      "condition": null,
      "showCondition": null,
      "items": null,
      "delimiter": true,
      "useRandomItems": null,
      "randomItemsCount": null
    },
    {
      "id": "occupationAndEmploym",
      "title": "Your occupation and employment",
      "localizedTitle": {
        "values": [
          {
            "lang": "en",
            "value": "Your occupation and employment"
          }
        ]
      },
      "desc": "Please select the options that best describe your situation.",
      "localizedDesc": {
        "values": [
          {
            "lang": "en",
            "value": "Please select the options that best describe your situation."
          }
        ]
      },
      "condition": null,
      "showCondition": null,
      "items": [
        {
          "id": "employment_status",
          "title": "What best describes your current employment status?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "What best describes your current employment status?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "selectDropdown",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "private_sector_employee",
              "title": "Private sector employee",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Private sector employee"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "government_sector_employee",
              "title": "Government sector or local authority employee",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Government sector or local authority employee"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "self_employed",
              "title": "Self-employed individual/professional",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Self-employed individual/professional"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "business_owner",
              "title": "Business owner",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Business owner"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "student",
              "title": "Student",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Student"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "retired",
              "title": "Retired",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Retired"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "unemployed",
              "title": "Unemployed",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Unemployed"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "other",
              "title": "Other",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Other"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "other_employment_status",
          "title": "Please specify your employment status",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "Please specify your employment status"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "text",
          "required": true,
          "format": null,
          "condition": "occupationAndEmploym.employment_status = other",
          "showCondition": null,
          "placeholder": "Add details",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": "Add details"
              }
            ]
          },
          "options": null,
          "arbitraryDocType": null
        },
        {
          "id": "occupation_position",
          "title": "What best describes your role?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "What best describes your role?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "selectDropdown",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "manager",
              "title": "Manager",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Manager"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "professional",
              "title": "Professional",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Professional"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "technicians_associate_professional",
              "title": "Technician and associate professional",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Technician and associate professional"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "clerical_support_worker",
              "title": "Clerical support worker",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Clerical support worker"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "service_sales_worker",
              "title": "Service and sales worker",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Service and sales worker"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "skilled_agricultural_forestry_fishery",
              "title": "Skilled agricultural, forestry and fishery worker",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Skilled agricultural, forestry and fishery worker"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "craft_related_trades_worker",
              "title": "Craft and related trades worker",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Craft and related trades worker"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "plant_machine_operator_assemblers",
              "title": "Plant and machine operator, and assemblers",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Plant and machine operator, and assemblers"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "elementary_occupation",
              "title": "Elementary occupation",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Elementary occupation"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "not_applicable",
              "title": "Not applicable",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Not applicable"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "occupation",
          "title": "What sector do you work in?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "What sector do you work in?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "selectDropdown",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "accounting_audit",
              "title": "Accounting/Audit",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Accounting/Audit"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "payments_emoney",
              "title": "Payments/e-money services",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Payments/e-money services"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "currency_exchange",
              "title": "Currency exchange",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Currency exchange"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "banking_lending",
              "title": "Banking/Lending",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Banking/Lending"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "consultancy_legal",
              "title": "Consultancy/Legal",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Consultancy/Legal"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "public_administration",
              "title": "Public sector",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Public sector"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "health_care_medical",
              "title": "Health care/Medical services",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Health care/Medical services"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "education",
              "title": "Education",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Education"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "informational_technologies",
              "title": "Informational technologies",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Informational technologies"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "construction_repair",
              "title": "Construction/Repair",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Construction/Repair"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "real_estate",
              "title": "Real estate",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Real estate"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "manufacturing",
              "title": "Manufacturing",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Manufacturing"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "pr_marketing",
              "title": "PR/Marketing",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "PR/Marketing"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "trade_food_products",
              "title": "Trade in food products",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Trade in food products"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "wholesale",
              "title": "Wholesale",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Wholesale"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "repair_motor_vehicles",
              "title": "Motor vehicle repair",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Motor vehicle repair"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "transportation_logistics",
              "title": "Transportation and logistics",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Transportation and logistics"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "courier_post",
              "title": "Courier/Post services",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Courier/Post services"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "hospitality_leisure",
              "title": "Hospitality and leisure",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Hospitality and leisure"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "social_work",
              "title": "Social work activities",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Social work activities"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "freelance",
              "title": "Freelance",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Freelance"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "administrative_office",
              "title": "Administrative services",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Administrative services"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "other_trade_sales",
              "title": "Other trade and sales",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Other trade and sales"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "investments_trading",
              "title": "Investments/Trading",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Investments/Trading"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "securities_trading_otc",
              "title": "OTC securities trading",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "OTC securities trading"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "high_value_assets",
              "title": "High-value asset dealers",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "High-value asset dealers"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "cryptocurrencies",
              "title": "Cryptocurrencies",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Cryptocurrencies"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "precious_metals_stones",
              "title": "Precious Metals/Stones",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Precious Metals/Stones"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "pawnshops",
              "title": "Pawnshops",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Pawnshops"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "cross_border_cash_metals",
              "title": "Cross-border cash & metals",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Cross-border cash & metals"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "mining_extractive",
              "title": "Mining extractive industries",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Mining extractive industries"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "energy",
              "title": "Energy",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Energy"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "trade_petrol",
              "title": "Trade in petrol products",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Trade in petrol products"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "trade_medicines",
              "title": "Trade in medicines",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Trade in medicines"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "non_profit_entities",
              "title": "Non-profit legal еntities",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Non-profit legal еntities"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "gaming_online",
              "title": "Gaming/Online gaming",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Gaming/Online gaming"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "gambling_online",
              "title": "Gambling/Online gambling",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Gambling/Online gambling"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "eu_funds",
              "title": "EU funds utilization",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "EU funds utilization"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "adult",
              "title": "Adult",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Adult"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "insurance_security",
              "title": "Insurance/Security",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Insurance/Security"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "utilities_infrastructure",
              "title": "Utilities/Infrastructure",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Utilities/Infrastructure"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "auto_aviation",
              "title": "Auto/Aviation",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Auto/Aviation"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "agriculture_forestry",
              "title": "Agriculture, forestry and fishing",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Agriculture, forestry and fishing"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "travel_tourism",
              "title": "Travel/Tourism",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Travel/Tourism"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "information_communication",
              "title": "Information and communication",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Information and communication"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "art_entertainment_sport",
              "title": "Art/Entertainment/Sport",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Art/Entertainment/Sport"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "scientific_technical",
              "title": "Scientific and technical activities",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Scientific and technical activities"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "other",
              "title": "Other",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Other"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "other_occupation",
          "title": "Please specify the sector",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "Please specify the sector"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "text",
          "required": true,
          "format": null,
          "condition": "occupationAndEmploym.occupation = other",
          "showCondition": null,
          "placeholder": "Add details",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": "Add details"
              }
            ]
          },
          "options": null,
          "arbitraryDocType": null
        }
      ],
      "delimiter": null,
      "useRandomItems": null,
      "randomItemsCount": null
    },
    {
      "id": null,
      "title": null,
      "localizedTitle": {
        "values": [
          {
            "lang": "en",
            "value": ""
          }
        ]
      },
      "desc": null,
      "localizedDesc": {
        "values": [
          {
            "lang": "en",
            "value": ""
          }
        ]
      },
      "condition": null,
      "showCondition": null,
      "items": null,
      "delimiter": true,
      "useRandomItems": null,
      "randomItemsCount": null
    },
    {
      "id": "incomeAndExpectedTur",
      "title": "Income and card usage",
      "localizedTitle": {
        "values": [
          {
            "lang": "en",
            "value": "Income and card usage"
          }
        ]
      },
      "desc": "Approximate values are fine.",
      "localizedDesc": {
        "values": [
          {
            "lang": "en",
            "value": "Approximate values are fine."
          }
        ]
      },
      "condition": null,
      "showCondition": null,
      "items": [
        {
          "id": "client_monthly_net_income",
          "title": "What is your monthly income after tax?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "What is your monthly income after tax?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "select",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "less_than_1000_eur",
              "title": "Less than 1,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Less than 1,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_1001_and_5000_eur",
              "title": "Between 1,001 and 5,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 1,001 and 5,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_5001_and_10000_eur",
              "title": "Between 5,001 and 10,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 5,001 and 10,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_10001_and_15000_eur",
              "title": "Between 10,001 and 15,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 10,001 and 15,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "more_than_15000_eur",
              "title": "More than 15,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "More than 15,000 EUR"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "type_of_incoming_funds",
          "title": "Where will the money you add to your card come from?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "Where will the money you add to your card come from?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "select",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "domestic",
              "title": "From within my country",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "From within my country"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "intra_eea",
              "title": "From within the EU/EEA",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "From within the EU/EEA"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "cross_border",
              "title": "From outside the EU/EEA",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "From outside the EU/EEA"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "expected_incoming_monthly_eur",
          "title": "How much money do you expect to add or receive to your card each month?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "How much money do you expect to add or receive to your card each month?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "select",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "less_than_1000_eur",
              "title": "Less than 1,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Less than 1,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_1001_and_5000_eur",
              "title": "Between 1,001 and 5,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 1,001 and 5,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_5001_and_10000_eur",
              "title": "Between 5,001 and 10,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 5,001 and 10,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_10001_and_15000_eur",
              "title": "Between 10,001 and 15,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 10,001 and 15,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "more_than_15000_eur",
              "title": "More than 15,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "More than 15,000 EUR"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "expected_outgoing_monthly_eur",
          "title": "How much money do you expect to spend from your card each month?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "How much money do you expect to spend from your card each month?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "select",
          "required": null,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "less_than_1000_eur",
              "title": "Less than 1,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Less than 1,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_1001_and_5000_eur",
              "title": "Between 1,001 and 5,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 1,001 and 5,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_5001_and_10000_eur",
              "title": "Between 5,001 and 10,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 5,001 and 10,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_10001_and_15000_eur",
              "title": "Between 10,001 and 15,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 10,001 and 15,000 EUR"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "more_than_15000_eur",
              "title": "More than 15,000 EUR",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "More than 15,000 EUR"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        },
        {
          "id": "expected_monthly_frequency_incoming_transfer",
          "title": "How often will you add money to your card?",
          "localizedTitle": {
            "values": [
              {
                "lang": "en",
                "value": "How often will you add money to your card?"
              }
            ]
          },
          "desc": "",
          "localizedDesc": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "type": "select",
          "required": true,
          "format": null,
          "condition": null,
          "showCondition": null,
          "placeholder": "",
          "localizedPlaceholder": {
            "values": [
              {
                "lang": "en",
                "value": ""
              }
            ]
          },
          "options": [
            {
              "value": "less_than_2_times",
              "title": "Less than 2 times",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Less than 2 times"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "between_3_5_times",
              "title": "Between 3-5 times",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "Between 3-5 times"
                  }
                ]
              },
              "score": null
            },
            {
              "value": "more_than_6_times",
              "title": "More than 6 times",
              "localizedTitle": {
                "values": [
                  {
                    "lang": "en",
                    "value": "More than 6 times"
                  }
                ]
              },
              "score": null
            }
          ],
          "arbitraryDocType": null
        }
      ],
      "delimiter": null,
      "useRandomItems": null,
      "randomItemsCount": null
    }
  ]
}

FAQ

Visit Help Center for Users and Help Center for Merchants

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