Receive stablecoins via Payment Links

Use this method to add crypto payments to your checkout flow and collect payments from your customers. You have the option to build your own UI using the API response or redirect your user to a pre-built Hosted Payments Page.

Example use case: this flow is useful for platforms that collect payments from their customers. For example, a trading platform wants to implement a deposit feature, allowing its customers to top up their accounts for futures trading. Customers would go to the cashier, select cryptocurrency as the payment method, and enter the amount they want to deposit. Then, they would be redirected to the Hosted Payments Page to select the cryptocurrency they want to use for the deposit. Here BVNK acts as the provider for cryptocurrency payments.

BVNK generates a wallet address for your customer to send funds to. BVNK monitors the blockchain to detect incoming transactions to the wallet address. Once funds are received, BVNK converts the stablecoins and settles you in fiat, a different stablecoin or the same stablecoin depending on your preference.

Collect payments

To accept stablecoin payments from your customers, do the following:

Send the POST /api/v1/pay/summary request with a similar body. Remember to set the type parameter to IN to collect payments from your customers:

{
    "walletId": "a:25022613287255:zmHs0pg:1",
    "type": "IN",
    "amount": 10,
    "currency": "USD",
    "expiryMinutes": 30,
    "reference": "test_reference_in_Qa4wy9",
    "returnUrl": "https://your-url-here.com/status",
    "payInDetails": {
        "currency": "USDT"
    },
    "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe0332",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "type": "ORIGINATOR",
                "entityType": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
                "countryCode": "DE"
            }
        ]
    }
}

In the request, specify at least the following parameters:

Parameter	Required	Description
`walletId`	✅	Unique ID of the receiving wallet where you want the funds to settle in your BVNK account.
`reference`	✅	Reference relating to the payment that you and your customer will see. You can place any string here.
`amount`	✅	Amount required to complete the payment. Minimum deposit: €5.
`currency`	✅	Currency code you want to display the price in for the customer on the BVNK hosted page, or in your own UI.
`returnUrl`	❌	URL that takes the customer back to your platform when they click a “back to merchant” button after initiating the pay-in on the BVNK hosted payments page.
`redirectUrl`	❌	URL that redirects customers to the BVNK Hosted Payments Page where they can make the payment. You can create your own payment page using the endpoint's request and response fields. The minimum required set is: `displayCurrency`, `paidCurrency.amount` (to show how much they have to pay), `exchangeRate`, `address` (to which the customer has to pay).
`type`	✅	Transaction type. Use `IN` to collect payments from your customers.
`expiryMinutes`	❌	Time limit granted to end-users for completing incoming payments. If the parameter is left blank in your request, BVNK will default it to 2880 minutes (48 hours).
`payInDetails.currency`	❌	Currency for incoming payments. Set the value if you already know the currency your end-user uses for pay-ins, to skip the cryptocurrency selection screen. Leave the value blank to allow your customers to specify the desired currency.
`payInDetails.protocol`	❌	Protocol is strictly required when supplying `payInDetails.currency`. For the complete list of supported protocols for each currency, refer to the Currencies document.

You can specify the currencies that are available for your customers while making the payment with the currencyOptions parameter. This object is not mandatory; however, if provided, it restricts the currencies that can be used for the transaction. If currencyOptions is not specified, the customers can deposit funds in any of the 16 available currencies supported by the BVNK platform. For the complete list of supported currencies and protocols, refer to the Supported Currencies API.

The following example limits the list of available currencies to ETH and USDT.

{
    "walletId": "a:25022613287255:zmHs0pg:1",
    "amount": 2.0,
    "currency": "ETH",
    ...
    "currencyOptions": [
    {
      "code": "ETH"
    },
    {
      "code": "USDT"
    }
  ]
}

Upon successfully submitting the request, you receive the following response:

Response

{
    "uuid": "3332388b-43cd-45a1-ad1b-7df5e5f4dc6e",
    "merchantDisplayName": "Euro Company",
    "walletId": "a:25022613287255:zmHs0pg:1",
    "dateCreated": 1728647621633,
    "expiryDate": 1728649421633,
    "quoteExpiryDate": 1728649422000,
    "acceptanceExpiryDate": 1728647652000,
    "quoteStatus": "ACCEPTED",
    "reference": "test_reference_in_Qa4wy9",
    "type": "IN",
    "subType": "merchantPayIn",
    "status": "PENDING",
    "displayCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "EUR",
        "amount": 9.15,
        "actual": 0
    },
    "paidCurrency": {
        "currency": "USDT",
        "amount": 10.008422,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "EUR",
        "amount": 0.09,
        "actual": 0
    },
    "networkFeeCurrency": null,
    "displayRate": {
        "base": "USDT",
        "counter": "USD",
        "rate": 0.999158508704
    },
    "exchangeRate": {
        "base": "USDT",
        "counter": "EUR",
        "rate": 0.91423
    },
    "address": {
        "address": "0x7b686317f8ed2c2bc3bbd060464f1939359a00e3",
        "tag": null,
        "protocol": "ERC20",
        "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x7b686317f8ed2c2bc3bbd060464f1939359a00e3&uint256=10008422",
        "alternatives": [
            {
                "address": "0xab12ec2f0e47c45ac8ff0c3914fb426d5ef9541a",
                "tag": null,
                "protocol": "BEP20",
                "uri": "0xab12ec2f0e47c45ac8ff0c3914fb426d5ef9541a",
                "alternatives": []
            },
            {
                "address": "0x3f2b71f5cbca1e4cda0948208f67706a1a519c8e",
                "tag": null,
                "protocol": "POLYGON",
                "uri": "0x3f2b71f5cbca1e4cda0948208f67706a1a519c8e",
                "alternatives": []
            },
            {
                "address": "TYbVJodUGrkWJSWSVnHjXHU6g8RC7AvPE6",
                "tag": null,
                "protocol": "TRC20",
                "uri": "TYbVJodUGrkWJSWSVnHjXHU6g8RC7AvPE6",
                "alternatives": []
            }
        ]
    },
    "returnUrl": "https://your-url-here.com/status",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=3332388b-43cd-45a1-ad1b-7df5e5f4dc6e",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": [],
    "flow": "DEFAULT",
    "twoStep": false,
    "metadata": {
    "deviceType": "desktop",
    "sessionId": "abcdef123456",
    "userSegment": "premium",
    "campaignId": "promo-spring-2025"
    },
"customerId": "ba388054-4512-441e-a9c4-cbe9b0fe0332"
}

Here, take note of the redirectURL variable, which is used to direct customers to the Hosted Payments Page for digital asset selection.

Handle errors

If a customer uses an incorrect currency, BVNK can still process the payment. However, you have to show them a disclaimer forcing to use the correct currency, or the payment can be declined, or your funds could be lost.

Collect payments​

Handle errors​

Collect payments

Handle errors