Skip to content

Cryptocurrency transactions

BV Integration option

This integration option allows customers and merchants make payments and payouts in cryptocurrencies, even if the currencies of their wallets differ.

To make a transaction, it is required to indicate an amount in a fiat currency for exchange. An amount in a cryptocurrency equivalent to the amount in the fiat currency will be withdrawn from the crypto wallet of the sender and credited to the crypto wallet of the recipient.

This method supports the following cryptocurrencies:

Cryptocurrency name Cryptocurrency code Cryptocurrency standard
Binance Coin BNB
Bitcoin BTC
Bitcoin Cash BCH
Cardano ADA
Dai DAI
Dogecoin DOGE
Ethereum ETH
Litecoin LTC
Ripple XRP
Solana SOL
Tether USDT ERC20
Tether USDT TRC20
Tronix TRX
USD Coin USDC

Warning

After the transaction made by this alternative payment method is completed, the amount in the fiat currency can change.

In the webhook notifications and in the response to the transaction status request the processed amount in the fiat currency is assigned to the amount parameter.

The processed amount in the cryptocurrency is multiplied by 100 000 000 and rounded according to the mathematical rounding rules. It is assigned to the conversion.converted_amount parameter.

Payment

The cryptocurrency payment flow consists of the following stages:

  1. The customer initiates a payment, indicates an amount in a fiat currency which should be converted for a payment. Additionally, the customer can select the cryptocurrency of his/ her wallet.
  2. The merchant sends a request to process a payment with the parameters described below.
  3. The merchant redirects the customer to the URL of the acquirer's checkout page received in the response, so that the customer can complete the payment.
  4. On the acquirer's checkout page, the customer selects the cryptocurrency, if it has not been indicated before, and finalizes the payment.
  5. PaySage.io gets informed of the settled payment. If notification_url is submitted in the request, the merchant receives a webhook notification on the payment status and amounts debited in the fiat and crypto wallet currencies.

Info

In case of the integration with the payment widget or the payment page, it is the PaySage.io widget that displays the acquirer's checkout page in the iframe mode to your customer.

Request

Parameters of the payment widget and the payment token

In case of the integration with the payment widget or the payment page, initiate the widget or create a payment token with the following additional parameters:

Parameter Type Description
order object A section of payment parameters.
amount * required
 integer An amount in a fiat currency to convert for a payment. It should be specified in minimal currency units.
currency * required
 string A fiat currency in the ISO-4217 alpha-3 code format.
payment_method 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 fiat_to_crypto as an array element.
fiat_to_crypto object A section of parameters of the cryptocurrency payment method.
currency string A cryptocurrency code of the customer's wallet. See the list of possible codes above or in the cryptocurrency code reference.

API request parameters

In case of the API integration, send a payment request with the following additional parameters:

Parameter Type Description
amount * required
 integer An amount in a fiat currency to convert for a payment. It should be specified in minimal currency units.
currency * required
 string A fiat currency in the ISO-4217 alpha-3 code format.
method object A section of the payment method parameters.
type * required
 string Set to fiat_to_crypto.
currency * required
 string A cryptocurrency code of the customer's wallet. See the list of possible codes above or in the cryptocurrency code reference.
Example of the payment request 
{
    "request": {
        "amount":2900,
        "currency":"EUR",
        "description":"description",
        "test": true,
        "tracking_id":"your_unique_number",
        "language":"en",
        "notification_url":"https://example.com/notification",
        "return_url":"https://example.com/return",
        "method": {
            "type": "fiat_to_crypto"
        }
    }
}
Response

In case of the integration with the payment widget or the payment page, PaySage.io redirects the customer to the acquirer's checkout to complete the payment.

In case of the API integration, the response additionally contains the fiat_to_crypto section with the cryptocurrency payment details, as well as the form section with the details of the acquirer's checkout. Redirect your customer to the URL received as a value of the form.action parameter, so that he/ she can complete the payment.

Example of the response to a payment request 
{
    "transaction": {
        "uid": "2085ccec-33c8-4356-8d53-b081b4a07230",
        "type": "payment",
        "status": "pending",
        "amount": 2900,
        "currency": "EUR",
        "description": "description",
        "created_at": "2023-05-04T13:42:47Z",
        "updated_at": "2023-05-04T13:42:51Z",
        "method_type": "fiat_to_crypto",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/2085ccec-33c8-4356-8d53-b081b4a07230/735179255e5ff84e8b752f85452563c946f069bbb5cd0fc54541637a095354c0?language=en",
        "payment": {
            "status": "pending",
            "gateway_id": 2750,
            "ref_id": "f123456a-265b-4cd1-9823-2aa7123565fc",
            "message": "Transaction was initialized."
        },
        "fiat_to_crypto": {
            "type": "fiat_to_crypto",
            "currency": null
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "message": "Transaction was initialized.",
        "tracking_id": "your_unique_number",
        "test": true,
        "language": "en",
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },
        "gateway": {
            "iframe": true
        },
        "form": {
            "action": "{form_url}",
            "method": "GET",
            "fields": []
        }
    }
}

Payout

The cryptocurrency payout flow consists of the following stages:

  1. The customer initiates a payout request, indicates an amount in a fiat currency and the recipient's wallet ID.
  2. The merchant sends a payout request with the additional parameters described below.
  3. PaySage.io gets informed of the settled payment. If notification_url is submitted in the request, the merchant receives a webhook notification on the payout status and amounts debited in the fiat and crypto wallet currencies.
Request

Send a payout request with the following parameters:

Parameter Type Description
amount * required
 integer An amount in a fiat currency to convert for a payout. It should be specified in minimal currency units.
currency * required
 string A fiat currency in the ISO-4217 alpha-3 code format.
method object A section of the payment method parameters.
type * required
 string Set to fiat_to_crypto.
recipient_wallet_id * required
 string An ID of the customer's wallet to which the payout is transferred.
currency * required
 string A cryptocurrency code of the customer's wallet to which the payout is transferred. See the list of possible codes above or in the cryptocurrency code reference.
token_standard * required
 string A cryptocurrency standard. Required for a payout in USDT.

See the list of possible codes above.
tag string A payout recipient ID. Applicable for a payout in TRX.
Example of the payout request 
{
"request":{
    "amount":2500,
    "currency":"USD",
    "description":"description",
    "test": true,
    "tracking_id":"your_unique_number",
    "language":"en",
    "notification_url":"https://example.com/notification",
    "method":{
        "type":"fiat_to_crypto",
        "currency": "BTC",
        "recipient_wallet_id": "12345-abc-67890"
    }
  }
}
Response

The payout response additionally contains the fiat_to_crypto section with the parameters of the payment method used to make a payout.

Example of the response to a payout request 
{
  "transaction": {
        "uid": "1158d867-1c5d-4093-896e-bded62b59d20",
        "type": "payout",
        "status": "pending",
        "amount": 2500,
        "currency": "USD",
        "description": "description",
        "created_at": "2023-05-04T19:50:11Z",
        "updated_at": "2023-05-04T19:50:11Z",
        "method_type": "fiat_to_crypto",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/1158d867-1c5d-4093-896e-bded62b59d20/be8e9bf9b24c699392ae752d3f72e3757113193096ee8b7c294ddd3d4acd3faf?language=en",
        "payout": {
            "status": "pending",
            "gateway_id": 2750,
            "message": "Transaction was initialized."
        },
        "fiat_to_crypto": {
            "type": "fiat_to_crypto",
            "currency": "BTC",
            "recipient_wallet_id": "12345-abc-67890"
        },
        "customer": {
            "email": null,
            "ip": "127.0.0.1"
        },
        "message": "Transaction was initialized.",
        "tracking_id": "your_unique_number",
        "test": true,
        "language": "en",
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        }
    }
}

Webhook notifications

If notification_url is submitted in the transaction request, PaySage.io sends out a webhook notification with the following additional parameters:

Parameter Type Description
transaction object
amount * required
 integer An actual transaction amount in a fiat currency in minimal currency units that equals the amount in the cryptocurrency withdrawn from the sender's wallet for a payment or a payout.
currency * required
 string A fiat transaction currency in the ISO-4217 alpha-3 code format. For example, USD.
method_type * required
 string fiat_to_crypto
fiat_to_crypto object A section of the payment method parameters.
type * required
 string fiat_to_crypto
recipient_wallet_id * conditionally required
 string An ID of the customer's wallet to which the payout is transferred. Specified in the webhook notification on a payout transaction only.
conversion * required
 object A section of the transaction parameters in a cryptocurrency to which the transaction amount in the fiat currency was converted.
exchange_rate * required
 object A section of the exchange rate applicable to convert the transaction amount from the fiat to the cryptocurrency.
converted_currency * required
 string A cryptocurrency code of the customer's wallet. See the list of possible codes above or in the cryptocurrency code reference.
converted_amount * required
 integer A transaction amount in the cryptocurrency.
additional_data * required
 object A section of additional transaction details.
provider_raw * required
 object A section of additional transaction details provided by the acquirer.
Example of the webhook notification on a successful payment 
{
  "transaction": {
        "uid": "2085ccec-33c8-4356-8d53-b081b4a07230",
        "type": "payment",
        "status": "successful",
        "amount": 2900,
        "currency": "EUR",
        "description": "description",
        "created_at": "2023-05-04T13:42:47Z",
        "updated_at": "2023-05-04T13:45:01Z",
        "method_type": "fiat_to_crypto",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/2085ccec-33c8-4356-8d53-b081b4a07230/12db53fdb53b1655f08af6577d77469e61376e433aa627dfffc4f53f28afb82b?language=en",
        "payment": {
            "status": "successful",
            "gateway_id": 2750,
            "ref_id": "da37b123-dddf-4d31-88af-b2dcdefd2c86",
            "message": "Transaction was successfully processed."
        },
        "fiat_to_crypto": {
            "type": "fiat_to_crypto"
        },
        "customer": {
            "email": null,
            "ip": "127.0.0.1"
        },
        "message": "Transaction was successfully processed.",
        "tracking_id": "your_unique_number",
        "test": false,
        "language": "en",
        "paid_at": "2023-05-04T13:45:01Z",
        "additional_data": {
            "provider_raw": {
                "type": "IN",
                "uuid": "da37b123-dddf-4d31-88af-b2dcdefd2c86",
                "refund": null,
                "status": "COMPLETE",
                "address": {
                    "tag": null,
                    "uri": "0xC0Fdc9B1234aCE2D8f3B89C4472cae7727ABB6fe",
                    "address": "0xC0Fdc9B7715aCE2D8f3B89C1234cae7727ABB6fe",
                    "protocol": "ETH",
                    "alternatives": []
                },
                "refunds": [],
                "subType": "merchantPayIn",
                "reference": "2085ccec-33c8-4356-8d53-b081b4a07230",
                "returnUrl": "https://api.paysage.io/beyag/transactions/returns/63496cb932bc335674f362af4b6a36729923e401361c6d1fd0fd87ce21a0eea5/2085ccec-33c8-4356-8d53-b081b4a07230",
                "expiryDate": 1683208971000,
                "merchantId": "1234b7e5-07cd-456b-a6e3-678abf4bu89a",
                "dateCreated": 1683207771000,
                "displayRate": {
                    "base": "ETH",
                    "rate": 1692.29,
                    "counter": "EUR"
                },
                "feeCurrency": {
                    "actual": 1.111e-05,
                    "amount": 1.111e-05,
                    "currency": "BTC"
                },
                "quoteStatus": "PAYMENT_OUT_PROCESSED",
                "redirectUrl": "{form_url}",
                "exchangeRate": {
                    "base": "ETH",
                    "rate": 0.06484203,
                    "counter": "BTC"
                },
                "paidCurrency": {
                    "actual": 0.01713657,
                    "amount": 0.01713657,
                    "currency": "ETH"
                },
                "transactions": [
                    {
                        "hash": "0x76e7d5e12345f19b234bf9f37d088fc1234a3ed1bdc5087085a31c0eb9978ec3",
                        "risk": {
                            "level": "LOW",
                            "alerts": [],
                            "resourceName": "UNKNOWN",
                            "resourceCategory": "UNKNOWN"
                        },
                        "amount": 0.01713657,
                        "sources": [
                            "0xF282C3A8f95Ad256BA8DAFB251ef89B43dc6c52f"
                        ],
                        "dateCreated": 1683207883000,
                        "displayRate": {
                            "base": "ETH",
                            "rate": 1692.29,
                            "counter": "EUR"
                        },
                        "exchangeRate": {
                            "base": "BTC",
                            "rate": 15.4221,
                            "counter": "ETH"
                        },
                        "dateConfirmed": 1683207894000,
                        "networkFeeAmount": 0.015683724348894,
                        "networkFeeCurrency": "ETH"
                    }
                ],
                "walletCurrency": {
                    "actual": 0.00111117,
                    "amount": 0.00111117,
                    "currency": "BTC"
                },
                "displayCurrency": {
                    "actual": 29,
                    "amount": 29,
                    "currency": "EUR"
                },
                "quoteExpiryDate": 1683218586000,
                "merchantDisplayName": "Business Account",
                "acceptanceExpiryDate": 1683207807000
            },
            "payment_method": {
                "type": "alternative"
            }
        },
        "gateway": {
            "iframe": true
        },
        "conversion": {
            "exchange_rate": {
                "ETH_TO_EUR": 1692.29
            },
            "converted_amount": 1713657,
            "converted_currency": "ETH"
        }
    }
}

CB Integration option

Payment

Info

This integration option supports only `EUR` currency.
Request

Parameters of the payment widget and the payment token

In the case of the integration with the payment widget or the payment page, initiate the widget or create a payment token with the following additional parameters:

Parameter Type Description
order object A section of payment parameters.
amount * required
 integer The payment amount in EUR. It needs to be specified in minimal currency units.
currency * required
 string A fiat currency in the ISO-4217 alpha-3 code format. Always EUR.
payment_method 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 fiat_to_crypto as an array element.

Payment request parameters

Payment flow:

  1. The customer initiates the payment on the merchant's website.
  2. The merchant sends a payment request to PaySage.io.
  3. PaySage.io returns a response containing a form.action parameter with a URL where the customer needs to be redirected.
  4. The merchant redirects the customer to the URL from the response.
  5. The URL will display a payment page with the amount to be paid in EUR as well as the corresponding amount in cryptocurrency. The customer logs into their account or creates a new one, submits their card details and completes the payment.

The payment request needs to contain the following additional parameters:

Parameter Type Description
amount * required
 integer The payment amount in EUR. It needs to be specified in minimal currency units.
currency * required
 string A fiat currency in the ISO-4217 alpha-3 code format. Must be EUR.
method object A section of the payment method parameters.
type * required
 string fiat_to_crypto
Request example 
{
    "request": {
        "amount": 5000,
        "currency": "EUR",
        "description": "Cryptocurrency",
        "test": false,
        "tracking_id": "9379992",      
        "notification_url": "https://notification_url",
        "return_url": "https://return_url",      
        "method": {
            "type": "fiat_to_crypto"
        }
    }
}
Response

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

Response example 
{
    "transaction": {
        "uid": "5ca616cf-2079-4b67-a40b-fa8b3e516636",
        "type": "payment",
        "status": "pending",
        "amount": 5000,
        "currency": "EUR",
        "description": "Cryptocurrency",
        "created_at": "2024-05-24T13:55:23Z",
        "updated_at": "2024-05-24T13:55:24Z",
        "method_type": "fiat_to_crypto",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/5ca616cf-2079-4b67-a40b-fa8b3e516636/de9689f91a38c143bdcdf91036c3ea174e0e5cb95c9eb0a9982b1f40c5122b0b",
        "payment": {
            "status": "pending",
            "gateway_id": 4020,
            "ref_id": "lEaJDnvED3k1",
            "message": "Transaction was initialized."
        },
        "fiat_to_crypto": {
            "type": "fiat_to_crypto"
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "manually_corrected_at": null,
        "message": "Transaction was initialized.",
        "tracking_id": "9379992",
        "test": false,
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },      
        "gateway": {
            "iframe": false
        },
        "form": {
            "action": "https://gateway.cb.live/payments/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXJjaGFudCI6NSwib3JkZXIiOiI1Y2E2MTZjZi0yMDc5LTRiNjct",
            "method": "GET",
            "fields": []
        }
    }
}