Payment request callbacks

{
  "payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
  "foreign_id": "order_12345",
  "type": "payment_request",
  "status": "processing",
  "end_user_email": "[email protected]",
  "end_user_reference": "user_12345",
  "payment_request_amount": {
    "currency": {
      "iso": "EUR"
    },
    "amount": "100"
  },
  "payment_request_address": {
    "id": "019fd742-7b3c-71f8-9cf0-b17f5cc2ad5e",
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "convert_to": {
      "iso": "EUR"
    },
    "address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1"
  },
  "currency_sent": {
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "expected_amount": "115.99",
    "remaining_amount": "115.99",
    "received_amount": "0"
  },
  "expires_at": 1786023178,
  "fixed_at": 1786022886,
  "valid_until": 1786023178
}

{
  "payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
  "foreign_id": "order_12345",
  "type": "payment_request",
  "status": "processing",
  "end_user_email": "[email protected]",
  "end_user_reference": "user_12345",
  "payment_request_amount": {
    "currency": {
      "iso": "EUR"
    },
    "amount": "100"
  },
  "payment_request_address": {
    "id": "019fd742-7b3c-71f8-9cf0-b17f5cc2ad5e",
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "convert_to": {
      "iso": "EUR"
    },
    "address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1"
  },
  "currency_sent": {
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "expected_amount": "115.99",
    "remaining_amount": "115.99",
    "received_amount": "0"
  },
  "expires_at": 1786023178,
  "fixed_at": 1786022886,
  "valid_until": 1786023178
}

Successful flow
Expired
Failed for other reasons

The rate is fixed. You receive a callback with the processing status when the customer clicks Proceed to payment, or immediately for a fixed payment request.

The customer’s payment is detected. You receive another callback with the processing status for each transaction, and the transaction is listed in the transactions block of the callback.

The payment is complete. You receive a callback with the paid status once the full amount is received and confirmed.

If the customer hasn’t created any transactions during the lifespan or rate lock period, you receive a callback with the expired status.If the rate was never fixed, the callback has no payment address or currency_sent, because the customer didn’t proceed to payment.A transaction that arrives after expiry triggers another callback, with the transaction marked late_payment in transactions.

If the payment request wasn’t fully paid in time, you receive a callback with the failed status. Check status_reason and the status of each entry in transactions to find out why. The possible reasons are described in the status field below.

Body

application/json

payment_request_id

string

required

Payment request ID.

foreign_id

string

required

The foreign_id you provided when creating the payment request. Use it to map the callback to a customer or order in your system.

type

enum<string>

required

Available options:

payment_request

status

enum<string>

required

Payment request status. See also Payment request statuses.

processing: sent when the rate is fixed, that is, when the customer clicks Proceed to payment or immediately for a fixed payment request, and again each time a payment transaction is detected
paid: sent when the correct amount of funds has been received and the transactions got the required number of network confirmations. The received amount may be slightly less than the expected amount, according to your underpayment handling settings. If the customer paid more, the payment request is also paid as soon as the transactions are confirmed, and the extra is refunded to the customer, see Automatic refunds. An accepted underpayment gets the paid status only when the payment request lifespan ends
expired: the customer created no transactions during the lifespan or rate lock period
failed: the payment request was not fully paid in time, or the payment could not be processed. Possible reasons:
- underpayment: the customer sent a smaller amount than required, and the lifespan already ended. You can configure underpayment handling
- unconfirmed transaction: one or more transactions did not get the required number of network confirmations before the payment request expired
- invalid transaction: the transactions were cancelled in the blockchain or were smaller than the minimum deposit amount. Invalid transactions are not included in the callback
- payment restricted: the payment cannot be processed due to internal restrictions

After a payment request is paid, expired or failed, any subsequent incoming transaction triggers another callback with late_payment set to true for that transaction.

Available options:

processing,

paid,

expired,

failed

payment_request_amount

object

required

The requested amount.

Hide child attributes

payment_request_amount.currency

object

required

Hide child attributes

payment_request_amount.currency.iso

string

required

Currency code. See API currency codes.

payment_request_amount.currency.network_name

string

Blockchain network name. Present for cryptocurrencies.

payment_request_amount.amount

string

required

Requested amount.

expires_at

integer

required

Unix time in seconds when the payment request expires.

status_reason

string

Additional details about the status. Present only in some cases:

Underpayment accepted according to your payment handling rules: a paid payment request where an underpayment was accepted
The payment couldn't be processed because the transaction was invalid or couldn't be accepted: a failed payment request where the transactions were invalid, for example smaller than the minimum deposit amount
Service is restricted for the payer. Payments from this payer cannot be processed: a failed payment request where the payment could not be processed

end_user_email

string

The end_user_email you provided when creating the payment request. Present only if it was provided.

end_user_reference

string

The end_user_reference you provided when creating the payment request. Present only if it was provided.

payment_request_address

object

Details of the address the customer pays to. Present once the customer has proceeded to payment.

Hide child attributes

payment_request_address.id

string

required

Address ID.

payment_request_address.currency

object

required

Hide child attributes

payment_request_address.currency.iso

string

required

Currency code. See API currency codes.

payment_request_address.currency.network_name

string

Blockchain network name. Present for cryptocurrencies.

payment_request_address.address

string

required

Payment address.

payment_request_address.convert_to

object

Hide child attributes

payment_request_address.convert_to.iso

string

required

Currency code. See API currency codes.

payment_request_address.convert_to.network_name

string

Blockchain network name. Present for cryptocurrencies.

currency_sent

object

Amounts the customer is expected to send and has sent. Present once the customer has proceeded to payment.

Hide child attributes

currency_sent.currency

object

required

Hide child attributes

currency_sent.currency.iso

string

required

Currency code. See API currency codes.

currency_sent.currency.network_name

string

Blockchain network name. Present for cryptocurrencies.

currency_sent.expected_amount

string

required

Amount the customer is expected to send.

currency_sent.remaining_amount

string

required

Amount still to be paid. If it's less than the currency's minimum deposit amount, this is the minimum deposit amount instead. 0 once the payment request is paid. Doesn't change when a late payment arrives.

currency_sent.received_amount

string

required

Amount received so far. Doesn't include late payments or invalid transactions.

currency_received

object

The amount that will be credited to the merchant's account. Present only for paid payment requests.

Hide child attributes

currency_received.currency

object

required

Hide child attributes

currency_received.currency.iso

string

required

Currency code. See API currency codes.

currency_received.currency.network_name

string

Blockchain network name. Present for cryptocurrencies.

currency_received.amount

string

required

Amount received.

transactions

object[]

Payment transactions. Invalid transactions are not included.

Hide child attributes

transactions.id

string

required

Transaction ID.

transactions.currency

object

required

Hide child attributes

transactions.currency.iso

string

required

Currency code. See API currency codes.

transactions.currency.network_name

string

Blockchain network name. Present for cryptocurrencies.

transactions.address

string

required

Payment address.

transactions.amount

string

required

Transaction amount.

transactions.txid

string

required

Blockchain transaction hash.

transactions.status

enum<string>

required

Transaction status:

verifying: the transaction is detected and awaiting network confirmations
confirmed: the transaction has the required number of network confirmations
not_confirmed: the transaction did not get the required number of network confirmations in time

Available options:

verifying,

confirmed,

not_confirmed

transactions.late_payment

boolean

required

true if the transaction arrived after the payment request reached a final status: paid, expired or failed.

fees

object[]

Fees charged for the payment request, deducted from currency_received. Present only for paid payment requests. The processing fee is listed even if the customer pays it.

Hide child attributes

fees.type

string

required

Fee type, for example fee_payment_request_crypto_to_fiat.

fees.currency

object

required

Hide child attributes

fees.currency.iso

string

required

Currency code. See API currency codes.

fees.currency.network_name

string

Blockchain network name. Present for cryptocurrencies.

fees.amount

string

required

Fee amount.

fixed_at

integer

Unix time in seconds when the rate was fixed. Present only after the rate is fixed.

valid_until

integer

Unix time in seconds until which the fixed rate is valid. Present only after the rate is fixed.

Last modified on September 30, 2026

Reference

Deposits & withdrawals

Payment requests

Currencies

Exchange

Transactions

Account balance

System Health

Body