Payment Request

To test the API, make sure to include x-api-key in the header with your API key.

Create payment

post

Creates a payment link. You need to provide the amount and the currency of the payment in the request.

Authorizations

ApiKeyAuth

x-api-keystringRequired

Body

application/json

Payment creation request body

methodstring · enumOptional

A method to receive a payment.

Default: cryptoPossible values:

amountnumberRequired

The amount you want to receive from your customer.

processingFeeByUserbooleanOptional

If true, the initial amount will be increased to cover the platform fee.

platformFeeByUserbooleanOptional

Deprecated!, use processingFeeByUser

currencystring · min: 1Required

Specifies the cryptocurrency for the payment via tickers (refer to API glossary).

networkstring · enumRequired

Specifies the blockchain network for the payment via tickers (refer to API glossary).

Possible values:

customerIdstringOptional

Customer's ID for security purposes.

customerIpstring · min: 1Required

The customer's IP address, recorded for compliance purposes.

orderIdstring · min: 1Required

orderDescriptionstringOptional

Order description

additionalDatastringOptional

Additional information related to the payment, if needed.

webhookUrlone ofOptional

An optional URL where transaction status updates and payment notifications will be sent.

string · uriOptional

or

string · enumOptionalPossible values:

successUrlstring · uri · max: 256Optional

The URL to redirect to when the payment is successful.

Pattern: ^https?:\/\/

cancelUrlstring · uri · max: 256Optional

The URL to redirect to when the payment is failed.

Pattern: ^https?:\/\/

Responses

201

201

application/json

500

500

application/json

post

/v1/payment

HTTPcURLJavaScriptPython

POST /v1/payment HTTP/1.1
Host: api.bitnbox.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 401

{
  "method": "crypto",
  "amount": 1,
  "processingFeeByUser": true,
  "platformFeeByUser": true,
  "currency": "text",
  "network": "eth",
  "customerId": "text",
  "customerIp": "text",
  "orderId": "text",
  "orderDescription": "text",
  "additionalData": "text",
  "webhookUrl": "https://example.com",
  "products": [
    {
      "id": "text",
      "type": "01",
      "name": "text",
      "description": "text"
    }
  ],
  "successUrl": "https://example.com",
  "cancelUrl": "https://example.com"
}

{
  "orderId": "text",
  "status": "waiting",
  "method": "crypto",
  "currency": "text",
  "network": "text",
  "payAmount": 1,
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "checkoutUrl": "text",
  "appRedirectUrl": "text",
  "payAddress": "text",
  "payQrCodeUri": "text",
  "customerId": "text",
  "customerIp": "text",
  "processingFeeByUser": true,
  "products": [],
  "additionalData": "text",
  "webhookUrl": "https://example.com",
  "createdAt": "2026-02-03T15:29:01.402Z",
  "updatedAt": "2026-02-03T15:29:01.402Z",
  "expiredAt": "2026-02-03T15:29:01.402Z",
  "condition": "text"
}

appRedirectUrl - а link for the user to proceed to payment on the exchange side.

For web integration, it is recommended to open appRedirectUrl in a new browser tab (target=“_blank”) to ensure a correct user experience and avoid redirect blocking.

Get payment status by id

get

Get the actual information about the payment. You need to provide the ID of the payment in the request.

Authorizations

ApiKeyAuth

x-api-keystringRequired

Path parameters

idstringRequired

Unique identifier of the payment

Responses

200

200

application/json

get

/v1/payment/{id}/status

HTTPcURLJavaScriptPython

GET /v1/payment/{id}/status HTTP/1.1
Host: api.bitnbox.io
x-api-key: YOUR_API_KEY
Accept: */*

200

200

{
  "orderId": "text",
  "status": "waiting",
  "method": "crypto",
  "currency": "text",
  "network": "text",
  "payAmount": 1,
  "paymentId": "123e4567-e89b-12d3-a456-426614174000",
  "checkoutUrl": "text",
  "appRedirectUrl": "text",
  "payAddress": "text",
  "payQrCodeUri": "text",
  "customerId": "text",
  "customerIp": "text",
  "processingFeeByUser": true,
  "products": [],
  "additionalData": "text",
  "webhookUrl": "https://example.com",
  "createdAt": "2026-02-03T15:29:01.402Z",
  "updatedAt": "2026-02-03T15:29:01.402Z",
  "expiredAt": "2026-02-03T15:29:01.402Z",
  "condition": "text",
  "paidAmount": 1,
  "merchantAmount": 1,
  "paidAddress": "text"
}