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'.

POST/Payments/crypto

Authorization

oauth2

Header parameters

Body

application/jsontext/jsonapplication/*+json

terminalId*string

merchantId*string

requestedAmount*number (double)

referencenullable string

descriptionnullable string

cartItemsnullable array of CartItem (object)

customerCustomerRequest (object)

emailReceiptboolean

smsReceiptboolean

paymentUrlTypePaymentUrlType (enum)

web

redirectUrlnullable string

webhookUrlsnullable array of string

Response

200400401403

OK

Body

text/plainapplication/jsontext/json

trackingIdnullable string

paymentUrlsnullable array of PaymentUrl (object)

Request

JavaScriptCurlPython

const response = await fetch('/Payments/crypto', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "merchantId": "text",
      "requestedAmount": 0,
      "terminalId": "text"
    }),
});
const data = await response.json();

Response

200400

{
  "trackingId": "text",
  "paymentUrls": [
    {
      "type": "web",
      "url": "text"
    }
  ]
}

Example API call using curl:

curl -X 'POST' \
  'https://api.qa.devs.beadpay.io/payments/crypto' \
  -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": "https://beadpay.io"
}'

Important: For security, the required email field in the customer object is the only email address to which refund instructions will be sent in the event of an overpaid, underpaid or invalid payment. Submit the customer's email only.

Note: Payment receipts issued via Issue a Receipt may be sent to any valid email address.

Example response:

{
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "paymentUrls": {
    "type": "web",
    "url": "https://pay.qa.beadpay.io/6539fa89f0363f1722b377ef"
  }
}

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 Receipt

To send a receipt to a customer, use the following endpoint:

POST/Payments/crypto/request-receipt

Authorization

oauth2

Header parameters

Body

application/jsontext/jsonapplication/*+json

terminalId*string

merchantId*string

paymentCode*string

emailnullable string (email)

phonenullable string (tel)

Response

200400401403500

Success

Request

JavaScriptCurlPython

const response = await fetch('/Payments/crypto/request-receipt', {
    method: 'POST',
    headers: {
      "api-version": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "merchantId": "text",
      "paymentCode": "text",
      "terminalId": "text"
    }),
});
const data = await response.json();

Response

400500

text

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 a print, it is required to provide the following information for the customer:

Receipt Field	Description
Date-time	e.g. 1 Jan 2024 1:23 PM
Payment Code	paymentCode (e.g. HlbaHQjy29)
Status	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)
Refundable	Overpaid, Underpaid and Invalid only: the amount of crypto that will be refunded to the customer.