Create a payment request

Authorizations

X-Processing-Key

string

header

required

Your API key.

Headers

X-Processing-Signature

string

required

Hex-encoded HMAC-SHA512 signature of the request body, generated using your secret key.

Body

application/json

amount

required

The amount you want to receive from the customer, in currency, as a decimal string (for example, "100.50") or a number. It must be within the minimum and maximum payment request amounts. The number of decimal places allowed depends on the currency (2 for fiat currencies and stablecoins, 6 for other cryptocurrencies).

Example:

"100.50"

currency

object

required

The currency you want to receive.

Hide child attributes

currency.iso

string

required

Currency ISO code. For the list of all available currencies, see Currency codes.

Example:

"USD"

currency.network_name

string | null

Currency network name. Required for cryptocurrencies. Do not include for fiat currencies. For the list of all available networks, see Currency codes.

life_time_duration

integer | null

required

Payment request lifespan, in seconds (a whole number). Include either this parameter or life_time_date_time. At least one of these fields is required. The lifespan must be within the minimum and maximum lifespan for payment requests.

Required range: 300 <= x <= 5184000

Example:

3600

life_time_date_time

integer | null

required

The time the payment request expires, as a Unix timestamp in seconds (a whole number). Include either this parameter or life_time_duration. At least one of these fields is required. The same minimum and maximum lifespan apply as for life_time_duration.

Example:

1773768946

user_fee_percent

enum<integer>

default:0

Percentage of processing fees paid by the customer.

Currently, only two values are supported:

0 (the default) — the processing fee is paid by the merchant.
100 — the processing fee is paid by the customer.

Available options:

0,

100

payment_currency

object

The cryptocurrency your customer will pay in. Unlike currency, this must be a cryptocurrency — fiat currencies are not supported.

You can set both the currency and network or just the currency. If rate_mode is fixed, you must set both the currency and network.

Hide child attributes

payment_currency.iso

string

required

Cryptocurrency ISO code. For the list of all available currencies, see Currency codes.

payment_currency.network_name

string | null

Currency network name. Optional — omit to accept this cryptocurrency on any of its supported networks. For the list of all available networks, see Currency codes.

rate_mode

enum<string>

default:standard

This parameter controls the rate lock behavior. The value is case-sensitive.

standard - the customer will be able to choose the payment currency. The exchange rate will be locked after the customer confirms the selection on the first screen.
fixed - the exchange rate is locked immediately after the payment request is created. The first screen is skipped, and the customer is taken directly to the screen with the payment instructions. In this mode, you must specify both the currency and network in payment_currency, as well as provide sender_type, sender_data and end_user_email for the customer identification.

Available options:

standard,

fixed

end_user_email

string<email>

The customer's email address. It's filled in for the customer on the payment page. The customer gets an email when the payment is complete, and when a payment doesn't match the request (an underpayment that isn't accepted, an overpayment or a late payment): either a link to claim a refund, or a notice that the amount is too small to be refunded. Required if rate_mode is fixed.

Example:

"chris.customer@example.com"

end_user_reference

string

The unique ID of the customer this payment request is for. You can use it to group payment requests by customer.

sender_type

enum<string>

Type of the customer who sends the funds. Use natural if the sender is an individual person and legal if the sender is a legal entity. The selected type determines which fields must be included in sender_data.

sender_type and sender_data go together: if you provide one, you must also provide the other. Both are required if rate_mode is fixed. Otherwise, you can omit both, see Requesting data from the customer.

Available options:

natural,

legal

sender_data

Natural person · object

Details of the customer who sends the funds. Which fields are required depends on sender_type.

Natural person
Legal entity

Hide child attributes

sender_data.first_name

string

required

The sender's first name.

Maximum string length: 255

sender_data.last_name

string

required

The sender's last name.

Maximum string length: 255

sender_data.date_of_birth

string

The sender's date of birth, YYYY-MM-DD. Optional for a natural person.

description

string

Payment request description that the customer will see.

Example:

"Order #123"

foreign_id

string

Unique ID of the payment request in your system, case-insensitive. Must not contain personal data, such as the customer's name or email address. If omitted, the response doesn't include foreign_id, and callbacks send it as an empty string.

Maximum string length: 255

Example:

"order_123"

url_store

string<uri>

URL of the store page. The customer can click a button on the payment form to return to this URL (for example, if they change their mind or want to pick a different payment method). We recommend setting this to the URL of the checkout page.

Example:

"https://example.com/store"

url_success

string<uri>

URL of the success page. The customer will be able to return to this address once the payment is completed.

Example:

"https://example.com/success"

url_failed

string<uri>

URL of the failed payment page. The customer will be able to return to this address if the payment fails.

Example:

"https://example.com/fail"

Response

data

object

Hide child attributes

data.id

string

required

Payment request ID.

Example:

"0196f6a1-cab2-76fb-84c7-7e9ee9ddf6b4"

data.amount

string

required

Payment request amount.

Example:

"100.50"

data.currency

object

required

Hide child attributes

data.currency.iso

string

required

Payment request currency.

Example:

"USD"

data.currency.network_name

string | null

Network of the selected cryptocurrency. Not included for fiat currencies.

data.user_fee_percent

enum<integer>

required

Percentage of processing fees paid by the customer.

Available options:

0,

100

data.status

string

required

The status of the newly created payment request. Depends on rate_mode.

If the rate mode is standard, the status will be created.
If the rate mode is fixed, the status will be processing.

Example:

"created"

data.rate_mode

enum<string>

default:standard

required

The rate lock behavior.

standard - the customer will be able to choose the payment currency. The exchange rate will be locked after the customer confirms the selection on the first screen.
fixed - the exchange rate is locked immediately after the payment request is created. The first screen is skipped, and the customer is taken directly to the screen with the payment instructions.

Available options:

standard,

fixed

data.life_time

integer

required

Unix timestamp for when the payment request will expire, in seconds. Once the customer starts paying in a different currency, the payment request can end earlier, when the rate lock ends.

If rate_mode is fixed, this is the same as valid_until. A fixed-rate payment request lasts 1 hour at most, so a longer lifespan in the request is shortened to 1 hour.

Example:

1731427200

data.payment_link

string<uri>

required

Payment request URL.

data.valid_until

integer

Unix timestamp until which the exchange rate remains locked.

Included only if rate_mode is fixed.

Example:

1731427200

data.payment_currency

object

The cryptocurrency your customer will pay in. This is always a cryptocurrency, regardless of what currency is set to.

Hide child attributes

data.payment_currency.iso

string

required

Cryptocurrency ISO code. For the list of all available currencies, see API currency codes.

data.payment_currency.network_name

string

Currency network name.

data.end_user_email

string<email>

Customer email provided in the request.

Example:

"chris.customer@example.com"

data.description

string

Payment request description.

Example:

"Order #123 payment"

data.foreign_id

string

The foreign_id from the request. Omitted if the request didn't include one.

Example:

"payment_request_123"

data.url_store

string<uri>

URL of the store page.

data.url_success

string<uri>

URL of the success page.

data.url_failed

string<uri>

URL of the failed payment page.

data.end_user_reference

string

The end_user_reference from the request. Omitted if the request didn't include one.

data.payment_details

object

Additional information about the expected payment. Included only if rate_mode is fixed.

Hide child attributes

data.payment_details.address

object

required

Hide child attributes

data.payment_details.address.value

string

required

The crypto address to which the customer will need to send the funds.

data.payment_details.address.tag

string

Destination tag/memo for currencies that require it.

data.payment_details.expected_amount

string

required

The amount of cryptocurrency that the customer is expected to send.

data.payment_details.expected_currency

object

required

The cryptocurrency that the customer is expected to send.

Hide child attributes

data.payment_details.expected_currency.iso

string

required

The currency the customer will send.

Example:

"USDC"

data.payment_details.expected_currency.network_name

string | null

required

Network of the selected cryptocurrency.

data.payment_details.exchange_rate

object

The information about the exchange that will be performed after receiving funds from the customer.

This object is included only if payment_currency differs from currency.

Hide child attributes

data.payment_details.exchange_rate.from

object

Hide child attributes

data.payment_details.exchange_rate.from.iso

string

required

The currency the customer will send.

Example:

"USDC"

data.payment_details.exchange_rate.from.network_name

string

required

Network of the selected cryptocurrency.

Example:

"ethereum"

data.payment_details.exchange_rate.to

object

Hide child attributes

data.payment_details.exchange_rate.to.iso

string

required

The currency you will receive on your balance.

Example:

"USD"

data.payment_details.exchange_rate.to.network_name

string

Network of the selected cryptocurrency. Not included for fiat currencies.

data.payment_details.exchange_rate.rate

string

The exchange rate, in units of the to currency for 1 unit of the from currency.

Example:

"0.87"

data.payment_details.fee

object

The processing fee the customer pays, in the payment request currency. Included only if user_fee_percent is 100 (the customer pays the fee). It's included in expected_amount.

Hide child attributes

data.payment_details.fee.amount

string

required

Fee amount.

Example:

"0.15"

data.payment_details.fee.currency

object

required

Hide child attributes

data.payment_details.fee.currency.iso

string

required

Code of the fee currency, the same as the payment request currency. See API currency codes.

Example:

"USD"

data.payment_details.fee.currency.network_name

string

Network of the fee currency. Present only if the payment request currency is a cryptocurrency.

Reference

Deposits

Withdrawals

Payment requests

Exchanges

Currencies

Transactions

Account balance

System Health

Authorizations

Headers

Body

Response