Cryptocurrency transactions

XP Integration option

MerchantPay allows you to make payments and payouts in a cryptocurrency. This method supports the following cryptocurrencies:


Cryptocurrency name	Cryptocurrency code	Cryptocurrency standard
Ethereum	ETH
Tether	USDT	ERC20 Submit as an empty string ("") in requests.
Tether	USDT	TRC20
Tether	USDT	BEP20
Binance USD	BUSD	BEP20
Binance USD	BUSD	ERC20 Submit as an empty string ("") in requests.
Bitcoin	BTC
Dai	DAI	ERC20 Submit as an empty string ("") in requests.
Dai	DAI	BEP20
Dash	DASH
Dogecoin	DOGE
HUSD	HUSD	ERC20 Submit as an empty string ("") in requests.
Litecoin	LTC
TrueUSD	TUSD	ERC20 Submit as an empty string ("") in requests.
USD Coin	USDC	ERC20 Submit as an empty string ("") in requests.
USD Coin	USDC	BEP20
XRP	XRP	XRP
Huobi Token	HT	TRC20
HUSD	HUSD	TRC20
Ethereum	ETH	TRC20
Ethereum	ETH	BEP20
TRON	TRX	TRX
BNB	BNB	BNB
Cardano	ADA	BEP20
CasinoCoin	CSC	Ripple
Dexsport	DESU	BEP20
Axie Infinity	AXS	TRC20
Axie Infinity	AXS	ERC20 Submit as an empty string ("") in requests.
Bitcoin BEP2	BTCB	BEP20

Payment

The cryptocurrency payment flow consists of the following stages:

Your customer initiates a payment request in the selected cryptocurrency.
You initiate a widget, create a payment token or send a payment request with the additional parameters described below.
- In case of the integration with the payment widget, it is the MerchantPay widget that shows a payment instruction and the QR-code to your customer.
- In case of the API integration, you should use the received parameters and build a form to display the payment instruction.
Your customer makes a payment according to the received instruction.
MerchantPay gets informed of the payment. The widget shows the payment result to the customer. You receive a webhook notification on the payment status, if notification_url is submitted in your request.

Info

In the webhook notifications the payment amount is reported as multiplied by 100 000 000 and rounded according to the mathematical rounding rules.

Info

The QR code is valid for 30 minutes only.

Request

Parameters of the payment widget and the payment token

Initiate a widget or create a payment token with the following additional parameters:

object
A section of payment parameters.

amount required	integer Set to `0`. The actual payment amount is specified in a webhook notification.
currency required	string A cryptocurrency code. See the list of possible codes above or in the cryptocurrency code reference.

object
A section of parameters of the required payment methods.

types

required

array
An array of the available and enabled payment methods displayed to the customer. Add crypto_currency as an array element.

object
A section of parameters of the cryptocurrency payment method.

token_standard required	string A cryptocurrency standard. See the list of possible codes above.
tag conditionally required	string A payment recipient ID. Required for payments in TRX.

API request parameters

Send a payment request with the following additional parameters:

amount

required

integer
Set to 0. The actual payment amount is specified in a webhook notification.

currency

required

string
A cryptocurrency code. See the list of possible codes above or in the cryptocurrency code reference.

object
A payment method section in the request.

type required	string Set to `crypto_currency`.
token_standard required	string A cryptocurrency standard. See the list of possible codes above.
tag conditionally required	string A payment recipient ID. Required for payments in TRX.

Response

In case of the integration with the payment widget, the customer gets a payment instruction with the QR-code in the widget.

In case of the API integration, the response additionally contains the crypto_currency section with the following parameters:

object
A section of the cryptocurrency payment parameters.

type	string `crypto_currency`.
currency	string A code of the cryptocurrency.
id	string An identifier of the payment in the system of the payment method provider.
minimumAmount	string A minimal amount of the payment in the specified currency.
address	string A payment recipient ID.
destinationTag	string A payment recipient ID for payments in TRX.
rate	string A rate taken per a payment transaction in the specified currency.
qrCode	string A Base64-encoded QR code.
expDate	string An expiration date of the QR code in the UTC time zone.

Integrate the values of these parameters into your web form to show the relevant payment information to your customers.

Payout

The cryptocurrency payout flow consists of the following stages:

Your customer initiates a payout request in the selected cryptocurrency.
You send a payout request with the additional parameters described below.
The system checks the available balance and processes a payout.
You receive a webhook notification on the payout status, if notification_url is submitted in your request.

Info

In the webhook notifications the payment amount is reported as multiplied by 100 000 000 and rounded according to the mathematical rounding rules.

Request

To initiate a payout, send a payout request with the following parameters:

amount

required

integer
A payout amount. Multiply the actual amount by 100 000 000 and round it according to the mathematical rounding rules. See more information in the cryptocurrency code reference.

currency

required

string
A cryptocurrency code. See the list of possible codes above or in the cryptocurrency code reference.

object
A section of the payment method parameters.

type required	string Set to `crypto_currency`.
recipient_wallet_id required	string A wallet number to which the payout is transferred.
token_standard required	string A cryptocurrency standard. See the list of possible codes above.
tag conditionally required	string A payout recipient ID. Required for payments in TRX.

Response

The payout response additionally contains the crypto_currency section with the parameters which replicate the parameters from the request.

OP Integration option

This integration option lets you make payments and payouts in a cryptocurrency. This method supports the following cryptocurrencies:


Currency name	Currency code used in requests
TRON	TRX
Tether	USDT
Litecoin	LTC
Bitcoin Cash	BCH
USDD	USDD
USD Coin	USDC
Bitcoin	BTC
Binance USD	BUSD
BNB	BNB

Payment operation

Payment operation flow

The payment flow includes the following steps:

You initiate a request to get available currencies and networks for a payment, if needed. Otherwise, go to Step 3.
The MerchantPay system provides you with the list of cryptocurrencies and networks available for a payment.
You send a payment request with a selected currency and a network.
The response contains a link to which you should redirect your customer to complete a payment. The transaction has the pending status until the customer makes a payment.
Once the customer completes a payment, the funds are charged from your advanced balance ID.
You get a webhook notification about a payment status, if you send notification_url in the payment request.

Request for available currencies and networks

Request

To get the currencies and networks supported for a payment, send a request for available currencies and networks.

Response

The response to the request for available currencies and networks contains an array of currencies and networks supported for a payment.

The currencies and networks available for a payment should have the allowDeposit parameter set to true.

Successful response example

{
    "code": "S.0000",
    "status": "Successful",
    "friendly_message": "Successfully processed",
    "gateway_id": 1234,
    "provider_info": [
        {
            "currency": "TRX",
            "alias": "Tron",
            "allowDeposit": true,
            "allowWithdrawal": true,
            "priceUSD": "0.05908000",
            "networks": [
                {
                    "name": "tron",
                    "alias": "Tron (TRC20)",
                    "allowDeposit": true,
                    "allowWithdrawal": true,
                    "withdrawalFee": "1",
                    "withdrawalMin": 0,
                    "confirmations": 10,
                    "underMaintenance": false,
                    "isDefault": false,
                    "contract": null,
                    "addressRegex": "^T[1-9A-HJ-NP-Za-km-z]{35}$",
                    "tagRegex": ""
                }
            ]
        },
        {
            "currency": "USDT",
            "alias": "Tether USD",
            "allowDeposit": true,
            "allowWithdrawal": true,
            "priceUSD": "0.99820324",
            "networks": [
                {
                    "name": "solana",
                    "alias": "Solana",
                    "allowDeposit": true,
                    "allowWithdrawal": true,
                    "withdrawalFee": "0.8",
                    "withdrawalMin": 0,
                    "confirmations": 4,
                    "underMaintenance": false,
                    "isDefault": false,
                    "contract": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe9BenwNYB",
                    "addressRegex": "^[0-9a-zA-Z]{37,44}$",
                    "tagRegex": ""
                },
                {
                    "name": "ethereum",
                    "alias": "Ethereum (ERC20)",
                    "allowDeposit": true,
                    "allowWithdrawal": true,
                    "withdrawalFee": "3.2",
                    "withdrawalMin": 0,
                    "confirmations": 12,
                    "underMaintenance": false,
                    "isDefault": false,
                    "contract": "0xdac17f958d2ee523a2206206994597c13d841ec7",
                    "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
                    "tagRegex": ""
                }
            ]
        }
    ]
}

Payment transaction

Request

Send a payment request with the following parameters:

amount

required

integer
A payment amount. Multiply the actual amount by 100 000 000. See more information in the cryptocurrency code reference.

currency

required

string
A cryptocurrency code. See the list of possible codes above or in the cryptocurrency code reference. For example, USDT.

object
A section of a payment method.

type required	string A payment method type. Set to `crypto_currency`.
lifetime	string Lifetime of a payment request in seconds. By default, 43200 (12 hours).
token_standard required	string A name of the cryptocurrency network. Set to the `provider_info.networks.name` parameter value of a selected network from the response to the request for available currencies and networks.
balance_id required	string An advanced balance ID.

Request example

{
"request":{
    "amount":16400000,
    "currency":"LTC",
    "description":"description",
    "test": true,
    "tracking_id":"your_unique_number",
    "language":"en",
    "notification_url":"https://merchant.ltd/notification",
    "return_url":"https://merchant.ltd/return",
    "method": {
            "type": "crypto_currency",
            "lifetime": "43200",
            "token_standard": "litecoin",
            "balance_id": "2ceaad5d-751a-4bff-b951-787c341e33ad"
        }
}
}

Response

The payment response additionally contains the crypto_currency section with the name and details of the payment method, as well as the form section with the URL of a page to complete a payment.

Redirect your customer to the URL received as a value of the form.action parameter.

Successful response example

{
    "transaction": {
        "uid": "436cea91-1155-498c-8620-17e4866588b9",
        "type": "payment",
        "status": "pending",
        "amount": 16400000,
        "currency": "LTC",
        "description": "description",
        "created_at": "2022-11-09T12:38:51Z",
        "updated_at": "2022-11-09T12:38:52Z",
        "method_type": "crypto_currency",
        "receipt_url": "https://backoffice.universepay.eu/customer/transactions/436cea91-1155-498c-8620-17e4866589b9/53250553c58d4cf926eb1aa3fa9120f10b492df11a70a6c32f91dbac68619a71?language=ru",
        "payment": {
            "status": "pending",
            "gateway_id": 1234,
            "ref_id": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "message": "Transaction was initialized."
        },
        "crypto_currency": {
            "type": "crypto_currency",
            "balance_id": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "token_standard": "litecoin",
            "lifetime": 43200
        },
        "customer": {
            "ip": "127.0.0.1"
        },
        "message": "Transaction was initialized.",
        "tracking_id": "test crypto_currency",
        "test": true,
        "language": "ru",
        "billing_address": {
            "ip": "127.0.0.1"
        },
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },
        "form": {
            "action": "https://ocp.op.io/merchant/checkout/3f8dd21b-e7e8-4834-8abb-c5209c050d69",
            "method": "GET",
            "fields": []
        }
    }
}

Payout operation

Payout operation flow

The payout flow includes the following steps:

If needed, you initiate the following requests:
- a request to get available currencies and networks, in order you get the currencies and networks available for a payout, as well as a payout fee;
- an advanced balance request, in order you know if there are enough funds to pay a payout fee;
- an address request to get the list of addresses from which you can make a payout.
The system provides you with responses to requests made on Step 1.
You send a request to make a payout from a selected address.
The system sends out a response with the transaction status and details.

Info

A payout fee is charged from your advanced balance ID. If there are not enough funds to cover the fee, the payout request can be declined.

Request for available currencies and networks

Request

To get the currencies and networks supported for a payout, send a request for available currencies and networks.

Response

The response to the request for available currencies and networks contains an array of currencies and networks supported for a payout, as well as a payout fee.

The currencies and networks available for a payout have allowWithdrawal set to true. The withdrawalFee response parameter specifies a payout fee in cryptocurrency units.

Successful response example

{
    "code": "S.0000",
    "status": "Successful",
    "friendly_message": "Successfully processed",
    "gateway_id": 1234,
    "provider_info": [
        {
            "currency": "TRX",
            "alias": "Tron",
            "allowDeposit": true,
            "allowWithdrawal": true,
            "priceUSD": "0.05908000",
            "networks": [
                {
                    "name": "tron",
                    "alias": "Tron (TRC20)",
                    "allowDeposit": true,
                    "allowWithdrawal": true,
                    "withdrawalFee": "1",
                    "withdrawalMin": 0,
                    "confirmations": 10,
                    "underMaintenance": false,
                    "isDefault": false,
                    "contract": null,
                    "addressRegex": "^T[1-9A-HJ-NP-Za-km-z]{35}$",
                    "tagRegex": ""
                }
            ]
        },
        {
            "currency": "USDT",
            "alias": "Tether USD",
            "allowDeposit": true,
            "allowWithdrawal": true,
            "priceUSD": "0.99820324",
            "networks": [
                {
                    "name": "solana",
                    "alias": "Solana",
                    "allowDeposit": true,
                    "allowWithdrawal": true,
                    "withdrawalFee": "0.8",
                    "withdrawalMin": 0,
                    "confirmations": 4,
                    "underMaintenance": false,
                    "isDefault": false,
                    "contract": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
                    "addressRegex": "^[0-9a-zA-Z]{37,44}$",
                    "tagRegex": ""
                },
                {
                    "name": "ethereum",
                    "alias": "Ethereum (ERC20)",
                    "allowDeposit": true,
                    "allowWithdrawal": true,
                    "withdrawalFee": "3.2",
                    "withdrawalMin": 0,
                    "confirmations": 12,
                    "underMaintenance": false,
                    "isDefault": false,
                    "contract": "0xdac17f958d2ee523a2506206994597c13d931ec7",
                    "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
                    "tagRegex": ""
                }
            ]
        }
    ]
}

Advanced balance request

Request

To check if you have enough funds to cover a payout fee, send a balance query request, where you should set the account parameter to your advanced balance ID.

Response

The response specifies the advanced balance amount as a value of the provider_info.response.balance parameter.

Info

The balance amount is indicated in cryptocurrency units.

Successful response example

{
    "code": "S.0000",
    "status": "Successful",
    "friendly_message": "Successfully processed",
    "gateway_id": 1234,
    "account": "2ceaad5d-751a-4bff-b951-787c341e33ad",
    "amount": "3.400780144",
    "currency": "USD",
    "provider_info": {
        "success": true,
        "response": {
            "advancedBalanceId": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "currency": "USD",
            "blocked": false,
            "blockReason": null,
            "balance": "3.400780144",
            "availableCurrenciesForDeposit": [
                "USDT",
                "USDC",
                "USDD"
            ]
        }
    }
}

Address request

Request

To get the IDs and balances of the addresses available for a payout, send a GET request to https://apm.universepay.eu/beyag/on_chain_pay/addresses/{advanced_balance_id}, where {advanced_balance_id} is your advanced balance ID.

Request example

curl --location --request GET 'https://apm.universepay.eu/beyag/on_chain_pay/addresses/2ceaad5d-751a-4bff-b951-787c341e31ar' 
--header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Basic MTYwOmQxMDc1MjhlYjE3MzFlNWY5MTk2MWE2NDEyYTUyZWYyOWVm1WVhODc5ODZiZTk3YmM3NzI2NWU0NjEzNzM5YzE='

Response

The response contains an array of details of those addresses that are available for a payout.

Response example

{
    "success": true,
    "response": [
        {
            "id": "2d28222b-1d69-4dda-a590-1102efa590d7",
            "advancedBalanceId": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "currency": "LTC",
            "network": "litecoin",
            "address": "LTJdrbZ9wLS8MXkRCDZgSXZihpbgLWXfpo",
            "tag": "",
            "balance": "0"
        },
        {
            "id": "48f77919-c43f-4961-ab09-c3641d794eda",
            "advancedBalanceId": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "currency": "LTC",
            "network": "litecoin",
            "address": "LWMbqYuL49adXrHFHVuvgGuKWenuPxvHUX",
            "tag": "",
            "balance": "0"
        },
        {
            "id": "6b7b937f-e798-4003-a97e-eda28503ca9c",
            "advancedBalanceId": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "currency": "USDT",
            "network": "tron",
            "address": "TYyA96pmdiwcR75gqRLfpRPtipYPLz3qDh",
            "tag": "",
            "balance": "0"
        },
        {
            "id": "2470df4b-1eb4-4058-bf06-f10d1d995cef",
            "advancedBalanceId": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "currency": "USDT",
            "network": "tron",
            "address": "THaMuoyQL9s1iyrCeaDeQqo7pDnPnRFg7x",
            "tag": "",
            "balance": "23"
        },
        {
            "id": "586977ba-21b1-474c-98f0-d044948498a4",
            "advancedBalanceId": "2ceaad5d-751a-4bff-b951-787c341e33ad",
            "currency": "USDT",
            "network": "bsc",
            "address": "0xf1A8BD9384F505CE01DdE56d1E98c2cD9D060718",
            "tag": "",
            "balance": "0"
        }
    ]
}

Payout transaction

Request

To make a payout, send a payout request with the following parameters:

amount

required

integer
A payout amount. Multiply the actual amount by 100 000 000. See more information in the cryptocurrency code reference.

currency

required

string
A cryptocurrency code. See the list of possible codes above or in the cryptocurrency code reference. For example USDT.

required

object
A section of a payment method.

type required	string A payment method type. Set to `crypto_currency`.
network required	string A name of the network available for a payout. Set to the `name` parameter value of the selected network.
advanced_balance_id required	string An advanced balance ID.
address_id required	string An ID of the address from which a payout amount is charged. Set as a value of the `id` parameters of the response to the address request.
address required	string An ID of the address to which a payout amount is transferred.

Info

Before you make a transaction, please check the address to which a payout amount is transferred. In case of an error, a refund is not possible.

Request example

{
  "request": {
      "amount": 16700000,
      "currency": "LTC",
      "description": "payout description",
      "test": true,
      "expired_at": "2024-01-01T15:00:00+01:00",
      "tracking_id": "your_unique_number",
      "language": "en",
      "method": {
        "type": "crypto_currency",
        "network": "litecoin",
        "advanced_balance_id": "2ceaad5d-751a-4bff-b951-787c341e33ar",
        "address_id": "1e20326b-f34d-4c7d-8f0f-f2d57708016f",
        "address": "MDtmcmfXMwoJfBnh5AGqX5SteiZPAXqAdP"   
      }
  }
}

Response

The response contains the crypto_currency section with the payment method details from the request.

Successful response example

{
  "transaction": {
      "uid": "11fede31-7086-4620-8c46-25c8726a0156",
      "type": "payout",
      "status": "successful",
      "amount": 16700000,
      "currency": "LTC",
      "description": "payout description",
      "created_at": "2022-09-29T19:17:41Z",
      "updated_at": "2022-09-29T19:17:42Z",
      "method_type": "crypto_currency",
      "receipt_url": "https://backoffice.universepay.eu/customer/transactions/11fede31-7086-4620-8c46-25c8726a0156/5258a8f68f6bc45bc8d45a6febfeac9724c25cd56839da2b3138f3641c90ef07?language=en%22",
      "payout": {
      "status": "successful",
      "gateway_id": 1234,
      "ref_id": "65dd1c6d-9790-4039-be5a-9eff5736fcba",
      "message": "Transaction successfully processed."
      },
      "crypto_currency": {
      "type": "crypto_currency",
      "advanced_balance_id": "2ceaad5d-751a-4bff-b951-787c341e33ar",
      "address_id": "1e20326b-f34d-4c7d-8f0f-f2d57708016f",
      "address": "MDtmcmfXMwoJfBnh5AGqX5SteiZPAXqAdP"
      },
      "message": "Transaction successfully processed.",
      "tracking_id": "your_unique_number",
      "test": true,
      "language": "en",
      "paid_at": "2022-09-29T19:17:42+00:00",
      "additional_data": {
      "payment_method": {
          "type": "alternative"
      }
      }
  }
}

Transaction status check

To check a status of the payment, send a transaction status query.