# About

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

### Supported Assets

Mercuryo supports a wide range of cryptocurrencies and tokens for purchase, sale, and transfer through our APIs and platform.

For the always up-to-date list of supported assets, please refer to:  
[Which cryptocurrencies are supported?](https://help.mercuryo.io/hc/en-gb/articles/14495549158045-Which-cryptocurrencies-are-supported)

This list includes asset names, tickers, and network information, and is frequently updated.

# 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](https://tbtc.bitaps.com/)      | `msBE6aCaAesegu4VzbQW3L5xWBL8vi15Q7`           | Bitcoin                    |
| [ETH Sepolia](https://sepolia.etherscan.io/) | `0xbBC8f6B710359dbcdF02f9eb50Ade391890A6021`   | Ethereum (ETH) and USDT    |

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

### **Sandbox Payment Card Details**

**Card #1**

- Card Number `4444 4444 4444 3333`.
- Expiration Date `any future date`.
- CVV `123`.
- Cardholder Name `name + surname`.

**Card #2**

- Card Number `5555 4444 3333 1111`.
- Expiration Date `any future date`.
- CVV `123` for success, `555` for fail. 
- Cardholder Name `name + surname`.

**API URL:** [https://sandbox-cryptosaas.mrcr.io/v1.6/](https://sandbox-cryptosaas.mrcr.io/v1.6/).

**All the requests must contain:**

- Content Type: `application`/`json`
- Accept: `application`/`json`
- User Agent: `{PartnerName}`

**Recommendations:**
 
All Mercuryo API endpoints accept the `B2B-User-Ip` header, and it is strongly recommended that all requests contain the real IP address of end-user in this header. If there is no end-user's IP, Mercuryo reserves the right to reject transactions according to its internal rules.

## User Fees

Mercuryo charges fees for:

- Exchanging fiat money to crypto.
- Exchanging crypto to fiat money.

**Fee information must be available to the user at any moment.**

You can include additional fees to the list: `Mercuryo’s Fees + Your Fees = Total Fee`. Contact your account manager to adjust the fee policy.

## Sign-Up

The user must accept the [Terms of Service](https://mercuryo.io/legal/terms/) before signing up. You have to ask the user to agree to the Terms of Service on your front end. You will send user’s consent in the `accept` parameter of [`POST /b2b/user/sign-up`](/oor-api/api-reference/tag/user/post/b2b/user/sign-up).

All Mercuryo API endpoints — except for the authorization endpoints — require `b2b-bearer-token` header. Mercuryo uses the header to identify the merchant/user context.

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

### Steps

1. Ask your account manager to give you the `sdk-partner-token`.
2. Use the `sdk-partner-token` to sign authorization endpoints.
3. Use [`POST /b2b/user/sign-up`](/oor-api/api-reference/tag/user/post/b2b/user/sign-up) to sign up a user.

## Sign-In

Use [`POST /b2b/user/sign-in`](/oor-api/api-reference/tag/user/post/b2b/user/sign-in) to sign in a user, or use [`GET /b2b/user/refresh-token`](/oor-api/api-reference/tag/user/get/b2b/user/refresh-token) to refresh the `b2b-bearer-token`.

## Transaction ID

You can assign an ID to each transaction. Pass your transaction ID in the `merchant_transaction_id` field.

**Transaction ID format:** `^[A-Za-z0-9-_]{1,255}$`. Any lowercase and uppercase letter of the Latin alphabet, digits, underscore, and hyphen. Total length is up to 255 characters.

# KYC

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

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

SumSub is the major KYC procedure provider of Mercuryo. 

***Note:*** Please be aware that there must be only one 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.

## Identity Verification

**These documents can be acceptable identity verification:**

- Passport.
- ID card.
- Driving license.
- 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.

## KYC Requirements by Country

Depending on the user's country, a different set of documents is required for verification.

| Country / Region | Documents |
|------------------|-----------|
| EU + EEA, and non-EU countries | ID card / passport / residence permit / driving licence + Selfie |
| US | ID card / passport / residence permit / driving licence + SSN + Selfie |
| RU (IP outside EEA) | Passport / driving licence + POA + Selfie |
| RU (IP within EEA) | Passport / driving licence + residence permit + Selfie |
| BR (DOC_FREE + Selfie scenario) | CPF + Selfie |
| BR (DOC_FREE + Selfie scenario failed) | ID card / passport / residence permit / driving licence + Selfie |

## Integration

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

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

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

## SumSub Access Token

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

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

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

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

Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.

### Steps

1. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to get the KYC status. We can identify a user whom you registered by the email if we already have it:
    1. If in the list of `features`, `feature: crypto` is `complete`, then that’s it.
2. Use [`GET /b2b/kyc/access-token`](/oor-api/api-reference/tag/user/get/b2b/user/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_token&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](https://docs.sumsub.com/docs/verification-document-templates).
4. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to get the status for `feature: crypto`.
    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. 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 /b2b/kyc/access-token`](/oor-api/api-reference/tag/user/get/b2b/user/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_token&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](https://docs.sumsub.com/docs/verification-document-templates).
5. Use [`GET /b2b/kyc/documents`](/oor-api/api-reference/tag/user/get/b2b/kyc/documents) to fetch details on uploaded KYC documents.

## SumSub Share Token

> If you have already integrated SumSub KYC procedures, you can [share your SumSub applicants](https://developers.sumsub.com/api-reference/#sharing-applicants-between-partner-services) 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](https://www.youtube.com/watch?v=DpGd8wy07RM).
> 

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](https://docs.sumsub.com/docs/verification-document-templates).

If Mercuryo already has an applicant who requires verification, use [`POST /b2b/user/kyc-documents`](/oor-api/api-reference/tag/user/post/b2b/user/kyc-documents) or [`GET /b2b/kyc/access-token`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-access-token) to send additional documents. Or contact Mercuryo Support.

Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.

### 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 /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to get the KYC status. We can identify a user whom you registered by the email if we already have it:
    1. If in the list of `features`, `feature: crypto` is `complete`, then that’s it.
2. Use `SumSub API` `https://api.sumsub.com/resources/accessTokens/-/shareToken?applicantId=<applicant-Id>&forClientId=Mercuryo` and `ClientID Mercuryo` to get the share token.
3. Send the share token using [`POST /b2b/user/kyc-share-token`](/oor-api/api-reference/tag/user/post/b2b/user/kyc-share-token). The response will include an `access_token`.
4. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to get the status for `feature: crypto`.
    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. 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_token&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](https://docs.sumsub.com/docs/verification-document-templates).
5. Use [`GET /b2b/kyc/documents`](/oor-api/api-reference/tag/user/get/b2b/kyc/documents) to fetch details on uploaded KYC documents.

## User's Date of Birth

To simplify the off-ramp process to external cards and increase the sales conversion, it is recommended to provide user's date of birth. Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check if the date of birth is already set. If the value of the `is_birthday_set` property equals to `false`, use [`POST /b2b/user/birthday`](/oor-api/api-reference/tag/user/post/b2b/user/birthday) to submit user's date of birth. Please provide only the actual date of birth, not a random value.

## Submit Documents
 
> Manually send us users’ documents.
> 
 
Send us users’ scanned documents. 
 
Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.
 
### Steps
 
1. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to get the KYC status. We can identify a user who you registered by the email if we already have it:
     1. If in the list of `features`, `feature: crypto` is `complete`, then that’s it.
2. Use [`POST /b2b/user/kyc-documents`](/oor-api/api-reference/tag/user/get/b2b/kyc/documents) to send the identity verification documents. The response will include a `kyc_access_token`.
     1. Send us identity verification documents: ID card, driver license, passport, residence permit, proof of address (refer to the API Reference for the full list of required documents, and file naming conventions), and the country code (for `kyc_level`=`1`). The documents will be submitted to SumSub for verification.
3. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to get the status for `feature: crypto`.
     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. 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 `kyc_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_token&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](https://docs.sumsub.com/docs/verification-document-templates).
4. Use [`GET /b2b/kyc/documents`](/oor-api/api-reference/tag/user/get/b2b/kyc/documents) to fetch details on uploaded KYC documents.

# On-Ramp Scenarios

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

## Payment Card Crypto Purchase

> Buying crypto with fiat money using a payment card.
> 

Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use [`GET /b2b/user/card-limits`](/oor-api/api-reference/tag/user/get/b2b/user/card-limits) to get limit details. Use [`GET /b2b/user/card-limits-unverified`](/oor-api/api-reference/tag/user/get/b2b/user/card-limits-unverified) to check limits of the users who haven’t completed the KYC procedures.

### Slippage

If the price changes 1% or more upon calling the endpoint after acquiring rates, then the endpoint will contain an error with the 403004 code reading "Conversion rate has been changed”: Mercuryo won't create a transaction. Otherwise, Mercuryo will cover the price difference and the trade will have the rate which was acquired.

Acquire rates again if the elapsed time is more than an hour, because `trx_token` expires in one hour.

### Steps

1. Use [`GET /b2b/currencies`](/oor-api/api-reference/tag/helper/get/b2b/currencies) to get available currencies.
2. Use [`GET /b2b/oor/buy-methods`](/oor-api/api-reference/tag/buy/get/b2b/oor/buy-methods) to get available purchase methods.
3. Use the `card` payment method to buy crypto with user’s payment card.
4. Use [`GET /b2b/oor/buy-rates`](/oor-api/api-reference/tag/buy/get/b2b/oor/buy-rates) to get rates.
    1. The rates will be frozen and associated with the `trx_token`.
5. Use [`GET /b2b/user/cards`](/oor-api/api-reference/tag/user/get/b2b/user/cards) to get user’s saved payment cards. All new payment cards are saved automatically.
6. (Optional) Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to ensure that the user's billing address is present.
    1. If the value of the `is_billing_address_set` property equals to `false`, use [`POST /b2b/user/billing-address`](/oor-api/api-reference/tag/user/post/b2b/user/billing-address) to submit user's billing address.
7. Use [`POST /b2b/oor/buy`](/oor-api/api-reference/tag/buy/post/b2b/oor/buy) to start the transaction.
    1. Mercuryo creates the `buy_card` transaction.
    2. You will get a link to redirect the user. URL example: `https://payments.mercuryo.io/buy?parameters` (Production) or `https://sandbox-payments.mrcr.io/buy?parameters` (Sandbox).
    3. User will be prompted to enter their billing address unless you explicitly send the billing address before finalizing the transaction via [`POST /b2b/oor/buy`](/oor-api/api-reference/tag/buy/post/b2b/oor/buy).   
    4. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration manager to set the URL.

Get the transaction status using [`GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}`](/oor-api/api-reference/tag/helper/get/b2b/transactions).

## Crypto Purchase for PCI-DSS Certified

> Buying crypto with fiat money using a payment card.

The user must be signed in and verified (valid [KYC](/oor-api/guide#kyc)). Mercuryo won’t complete the transaction if the verification is expired. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to check user’s verification.

Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use [`GET /b2b/user/card-limits`](/oor-api/api-reference/tag/user/get/b2b/user/card-limits) to get limit details.

### Steps

1. Use [`GET /b2b/currencies`](/oor-api/api-reference/tag/helper/get/b2b/currencies) to get available currencies.
2. Use [`GET /b2b/oor/buy-methods`](/oor-api/api-reference/tag/buy/get/b2b/oor/buy-methods) to get available purchase methods.
3. Use the `card` payment method to buy crypto with user’s payment card.
4. Use [`GET /b2b/oor/buy-rates`](/oor-api/api-reference/tag/buy/get/b2b/oor/buy-rates) to get rates.
    1. The rates will be frozen and associated with the `trx_token`.
5. Use [`GET /b2b/user/cards`](/oor-api/api-reference/tag/user/get/b2b/user/cards) to get user’s saved payment cards. All new payment cards are saved automatically.
6. Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to ensure that the user's billing address is present.
    1. If the value of the `is_billing_address_set` property equals to `false`, use [`POST /b2b/user/billing-address`](/oor-api/api-reference/tag/user/post/b2b/user/billing-address) to submit user's billing address.
7. Use [`POST /b2b/oor/buy`](/oor-api/api-reference/tag/buy/post/b2b/oor/buy) to start the transaction. **For users with Brazil-issued payment cards and Brazilian reals only:** pass the `tin` parameter in [`POST b2b/oor/buy/card`](/oor-api/api-reference/tag/buy/post/b2b/oor/buy/card). A Taxpayer Identification Number — which is [CPF](https://en.wikipedia.org/wiki/CPF_number) for Brazil — is required.
    1. [`POST b2b/oor/buy/card`](/oor-api/api-reference/tag/buy/post/b2b/oor/buy/card) returns a 3-D secure redirect. This redirect contains `uri_template`. Redirect the user to the URL from `uri_template` and pass the parameters of the 3-D secure redirect.
    2. Create an iframe in your app to connect to the domain specified in the `src` attribute. Wait till `onLoad` is finished and pass the 3-D secure object in the iframe. Process the message at the front end after the 3-D secure form is complete.
    3. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration specialist to set the URL.

Get the transaction status using [`GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}`](/oor-api/api-reference/tag/helper/get/b2b/transactions).

# Off-Ramp Scenarios

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

## Payment Card Crypto Sell

> Selling crypto for fiat money and withdrawing funds to a payment card.
> 

The user must be signed in and verified (valid [KYC](/oor-api/guide#kyc)). Mercuryo won’t complete the transaction if the verification is expired. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to check user’s verification.

Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use [`GET /b2b/user/card-limits`](/oor-api/api-reference/tag/user/get/b2b/user/card-limits) to get limit details.

### Slippage

Wait for a deposit after successfully using [`POST /b2b/oor/sell`](/oor-api/api-reference/tag/sell/post/b2b/oor/sell). If the price changes upon receiving a deposit more than 5%, Mercuryo won't create a transaction. Mercuryo will return the deposit. Otherwise, Mercuryo will cover the slippage and the trade will have the rate which was acquired.

Acquire rates again if the elapsed time is more than an hour, because `trx_token` expires in one hour.

### Steps

1. Use [`GET /b2b/currencies`](/oor-api/api-reference/tag/helper/get/b2b/currencies) to get available currencies.
2. Use [`GET /b2b/oor/sell-methods`](/oor-api/api-reference/tag/sell/get/b2b/oor/sell-methods) to get available sell methods.
3. Use the `card` payment method to sell crypto and withdraw funds to user’s payment card.
4. Use [`GET /b2b/oor/sell-rates`](/oor-api/api-reference/tag/sell/get/b2b/oor/sell-rates) to get rates.
    1. The rates will be frozen and associated with the `trx_token`.
5. Use [`GET /b2b/user/cards`](/oor-api/api-reference/tag/user/get/b2b/user/cards) to get user’s saved payment cards. All new payment cards are saved automatically.
6. Use [`POST /b2b/oor/sell`](/oor-api/api-reference/tag/sell/post/b2b/oor/sell) to get a link to redirect the user.
    1. You will get a link to redirect the user. URL example: `https://payments.mercuryo.io/sell?parameters` (Production) or `https://sandbox-payments.mrcr.io/sell?parameters` (Sandbox).
    2. You will get an address to deposit crypto in the `GET` parameter of the redirect after successfully binding the payment card. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration specialist to set the URL.
    3. Mercuryo creates the `sell_card` transaction after receiving crypto. If the `sell_card` transaction fails, Mercuryo will return crypto to the specified address within two hours.
7. Get the `address` parameter value from the URL — which is a blockchain wallet — to send the crypto.
    1. Check the `signature` parameter value from the URL. It must be the same as the generated hash made up of `address` and `merchant_transaction_id` values in JSON, ex. `[”address”:”crypto_address”,“merchant_transaction_id”:”123”]`. This is a security measure to prevent the money theft.

Get the transaction status using [`GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}`](/oor-api/api-reference/tag/helper/get/b2b/transactions).

## Crypto Sell for PCI-DSS Certified

> Selling crypto for fiat money and withdrawing funds to a payment card.
> 

The user must be signed in and verified (valid [KYC](/oor-api/guide#kyc)). Mercuryo won’t complete the transaction if the verification is expired. Use [`GET /b2b/user/kyc-status`](/oor-api/api-reference/tag/user/get/b2b/user/kyc-status) to check user’s verification.

Use [`GET /b2b/user/contacts`](/oor-api/api-reference/tag/user/get/b2b/user/contacts) to check user's email verification status.

Check user limits before the transaction. Mercuryo won’t complete the transaction when beyond the limit. Use [`GET /b2b/user/card-limits`](/oor-api/api-reference/tag/user/get/b2b/user/card-limits) to get limit details.

### Steps

1. Use [`GET /b2b/currencies`](/oor-api/api-reference/tag/helper/get/b2b/currencies) to get available currencies.
2. Use [`GET /b2b/oor/sell-methods`](/oor-api/api-reference/tag/sell/get/b2b/oor/sell-methods) to get available sell methods.
3. Use the `card` payment method to sell crypto and withdraw funds to user’s payment card.
4. Use [`GET /b2b/oor/sell-rates`](/oor-api/api-reference/tag/sell/get/b2b/oor/sell-rates) to get rates.
    1. The rates will be frozen and associated with the `trx_token`.
5. Use [`GET /b2b/user/cards`](/oor-api/api-reference/tag/user/get/b2b/user/cards) to get user’s saved payment cards. All new payment cards are saved automatically.
6. Use [`POST /b2b/oor/sell/card`](/oor-api/api-reference/tag/sell/post/b2b/oor/sell/card) to get the address for depositing crypto.
    1. [`POST /b2b/oor/sell/card`](/oor-api/api-reference/tag/sell/post/b2b/oor/sell/card) returns a 3-D secure redirect object. This redirect contains `uri_template`. Redirect the user to the URL from `uri_template` and pass the parameters of the 3-D secure redirect.
    2. Mercuryo creates the `sell_card` transaction after receiving crypto.
        1. If the `sell_card` transaction fails, Mercuryo will return crypto to the specified address within two hours.
    3. Mercuryo will redirect the user to the success URL after confirming the payment card. Please contact your integration specialist to set the URL.

Get the transaction status using [`GET /b2b/transactions?merchant_transaction_id={merchant_transaction_id}`](/oor-api/api-reference/tag/helper/get/b2b/transactions).

# Transactions

## Buy with card option

> This is the case when purchase is made with the payment card.
>

1. `pending`: a transaction is in progress.
2. `failed`: a transaction is failed.
3. `cancelled`: a transaction is cancelled by the user or system.
4. `succeeded`: a transaction is successfully completed.

## Sell with card option

> This is the case when selling crypto for fiat money is made with the withdrawal of funds to a payment card.
>

1. `pending`: a transaction is in progress.
2. `failed`: a transaction is failed.
3. `cancelled`: a transaction is cancelled by the user or system.
4. `succeeded`: a transaction is successfully completed.

## Callbacks

Сontact your integration manager to set the callback URL.

### Body

```json
{
"url": "https:\/\/webhook.site\/#!\/6a4e734e-6c46-4de0-b67e-0166681aa250",
"tries": 15,
"payload": {
"data": {
"type": "buy",
"amount": "0.00239598",
"status": "paid",
"address": null,
"currency": "BTC",
"user_uuid": "447efa32-0afc-4326-b474-21e5a8624ce1",
"created_at": "2022-12-12 09:31:44",
"updated_at": "2022-12-12 09:32:08",
"fiat_amount": "40.00",
"fiat_currency": "EUR",
"merchant_transaction_id": "09516f6c766427412"
},
"eventId": "316e4fba-99bb-4322-8703-35542f477390"
},
"sign_key": "vjuKGL4fxMF6csD-3cr724TWPUPNTa8N",
"widget_id": "406a71aa-cc5f-471b-971b-6047dac6173f"
}
```

# FAQ

[`Visit Help Center`](https://help.mercuryo.io/hc/en-gb)

1. What crypto currencies does Mercuryo Support?

[Supported cryptocurrencies](https://help.mercuryo.io/hc/en-gb/articles/14805540483229-What-cryptocurrencies-does-Mercuryo-support-).

2. What crypto networks does Mercuryo Support?

[Supported crypto networks](https://help.mercuryo.io/hc/en-gb/articles/14805540483229-What-cryptocurrencies-does-Mercuryo-support-).

3. Where does Mercuryo operate?

Mercuryo is operational and allows end-users from all countries, except for the following [list](https://help.mercuryo.io/hc/en-gb/articles/14495532693021-Where-does-Mercuryo-operate-). The below details are used to identify whether end-user’s country is from non-operational list:

    - End-user's IP address.
    - End-user’s card issuer country.
    - Documents provided for passing KYC procedure which verify end-user’s country of residence.

Note that the Off-Ramp operations are available in selected [countries](https://help.mercuryo.io/hc/en-gb/articles/14831527435805-In-which-countries-is-the-off-ramp-solution-available-). 

4. Can I receive several callbacks of the same transaction with several statuses at the same time? Ex.: one transaction, one callback that is `completed` and another callback that is `pending`?

We send callbacks asynchronously. The callback delivery according to the status change is not guaranteed.

5. Is there “retry” for a failed callback? How does it work? Can I adjust it?

Yes, there is “retry”. You cannot adjust it. If the callback URL request doesn't return 200, we will be sending more requests asynchronously, but fewer with each day.

6. How is `sign_key` formed? How do I verify it?

We send the `X-Signature` header with a callback. This header contains the `sha256` hash generated from JSON of the entire `POST` request. `sign_key` is used as a key. Please contact your integration manager to obtain `sign_key`. You can verify a callback by encoding the received callback with the `sha256` algorithm and a key from the widget, and comparing the hash with the one from the header.

7. What is the time zone for `created_at` and `updated_at`?

The time zone is UTC.

8. Do you use `POST` to send callbacks?

Yes, we use `POST` to send callbacks.

9. When exactly do I receive callbacks?

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

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

You server must respond with the `200` http code.

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

It is assumed that a sell transaction must be completed within 6 hours. If the crypto is not received within this time, the transaction will be marked as failed due to a timeout. If the crypto is received after the 6-hour period, Mercuryo will return the crypto to the user's address.