Crypto Payments

Create Payment

Initiate crypto payment using this API endpoint:

Please note, to access this endpoint, please send the following header:

api-version: 0.2

This endpoint overrides version 0.1 with breaking changes. If no version header is specified, version '0.1' will be used and you will receive an error.

Once all our partners move to this endpoint the old one will be deprecated and the default version will be '0.2'.

Example API call using curl:

curl -X 'POST' \
  '' \
  -H 'Authorization: Bearer {token}' \
  -H 'api-version: 0.2' \
  -H 'Content-Type: application/json' \
  -d '{
  "terminalId": "000000000000000000000000",
  "merchantId": "000000000000000000000000",
  "requestedAmount": 10,
  "paymentUrlType": 0,
  "reference": "123",
  "redirectUrl": ""

Example response:

  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "paymentUrls": {
    "type": "web",
    "url": ""

The response contains:

  • trackingId to associate this payment to incoming webhooks to your specified webhook URL

  • Dictionary of paymentUrls with links to the Hosted Payment Page. For now, only Web URLs are supported.

After receiving the response, the payment app should redirect the user to the Hosted Payment Page where the customer payment interaction will be handled. All payment updates will be sent to the specified webhook URL for this terminal.

If redirectUrl is provided, the customer will be automatically redirected back to the specified link after completing payment at the Hosed Payment Page.

Possible values of paymentUrlType:

enum PaymentUrlType {
    Web = "web",

Also available here:Payment URL types enum.

Issue a Refund

In case you need to issue a refund for the payment, make a call to the following endpoint:

Possible values of refundType:

public enum RefundType
    Full = 0,
    Partial = 1,
    Underpaid = 2,
    Overpaid = 3

Also available here: Refund types enum.

Note: Customers will receive a link with pin code via email (and/or phone number) to complete the refund on their own device. Refunds will be manually approved by Bead Pay and customers will receive refunds to their specified wallet within 24 hours.

Issue a Receipt

To send a receipt to the customer after the payment has been completed, use the following endpoint:

You may specify email, phone number or both when issuing a receipt to a customer.

If you wish to issue a receipt to the customer via other means, such as printing, it is required to provide the following information for the customer:

Receipt FieldDescription


e.g. 1 Jan 2024 1:23 PM

Payment Code

paymentCode (e.g. HlbaHQjy29)


e.g. Complete

Total Price

requestedAmount value (e.g. 100.00 USD)

Exchange Rate

Exchange rate of payment crypto (e.g. 26,540.16 USD)

Amount Due

The amount due in crypto (e.g. 0.003768 BTC)

Amount Paid

Amount paid by customer in crypto, not including Network Cost (e.g. 0.003768 BTC)

Network Cost

Amount of Network Cost paid by the customer in crypto, if applicable (e.g. 0.00001 BTC)

Last updated