Payment request callbacks

{
  "payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
  "foreign_id": "order_12345",
  "type": "payment_request",
  "status": "processing",
  "end_user_email": "chris.customer@example.com",
  "end_user_reference": "user_12345",
  "payment_request_amount": {
    "currency": {
      "iso": "USD"
    },
    "amount": "100"
  },
  "payment_request_address": {
    "id": "019fd742-7b3c-71f8-9cf0-b17f5cc2ad5e",
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "convert_to": {
      "iso": "USD"
    },
    "address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1"
  },
  "currency_sent": {
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "expected_amount": "100.99",
    "remaining_amount": "100.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": "chris.customer@example.com",
  "end_user_reference": "user_12345",
  "payment_request_amount": {
    "currency": {
      "iso": "USD"
    },
    "amount": "100"
  },
  "payment_request_address": {
    "id": "019fd742-7b3c-71f8-9cf0-b17f5cc2ad5e",
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "convert_to": {
      "iso": "USD"
    },
    "address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1"
  },
  "currency_sent": {
    "currency": {
      "iso": "USDC",
      "network_name": "ethereum"
    },
    "expected_amount": "100.99",
    "remaining_amount": "100.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 the rate lock period, whichever ends first, you receive a callback with the expired status. A rate lock that ends before the lifespan ends the payment request too: it doesn’t wait for expires_at.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 (by the end of the lifespan or the rate lock period, whichever ends first), 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. An empty string if the payment request was created without one.

type

enum<string>

required

Available options:

payment_request

status

enum<string>

required

Payment request status.

processing: sent when the rate is fixed, that is, when the customer clicks Proceed to payment, or immediately for a fixed payment request. It's sent again each time a payment transaction is detected.
paid: the expected amount was received and confirmed, or an underpayment was accepted. An accepted underpayment gets this status when the lifespan or rate lock period ends, whichever comes first.
expired: the customer created no transactions during the lifespan or the rate lock period
failed: the payment request was not fully paid in time, or the payment could not be processed. See the possible reasons.

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's lifespan ends. If the rate lock ends earlier (valid_until), the customer must pay within the rate lock instead, and the payment request ends when the rate lock ends (with no transactions, it expires; with a partial payment, your underpayment handling rules apply).

status_reason

string

Additional details about the status. Present only in some cases, described in Payment request statuses:

Underpayment accepted according to your payment handling rules (paid)
The customer paid less than the requested amount. Based on your payment handling rules, the payment was not accepted (failed)
The payment couldn't be processed because the transaction was invalid or couldn't be accepted (failed)
Service is restricted for the payer. Payments from this payer cannot be processed (failed)

end_user_email

string<email>

The customer's email, as entered on the payment page. If you provided end_user_email when creating the payment request, the email field on the payment page is prefilled with it, and the customer can change it.

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.

payment_request_address.tag

string

Destination tag (memo) the customer must send with the payment. Present only for currencies that use tags, such as XRP, where several payment requests share one address and the tag tells them apart.

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 received for the payment request, in the payment request currency, before the fees in fees are deducted. Present only for paid payment requests. Note:

If the customer pays the processing fee (user_fee_percent is 100), this is the requested amount plus that fee, so you receive the requested amount after fees.
For an accepted underpayment, this is the amount actually paid, converted to the payment request currency.
For an overpayment, this is the requested amount, and the extra is refunded to the customer (unless it's too small to refund), see Automatic refunds.

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. Present once a transaction has been detected; before that, the field is left out rather than sent as an empty array. 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 doesn't have the required number of network confirmations yet. In a failed callback, it didn't get them before the payment request ended

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.

transactions.tag

string

Destination tag (memo) the transaction was sent with. Present only for currencies that use tags, such as XRP.

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: the payment was converted to a fiat payment request currency
fee_payment_request_crypto: the payment request currency is the cryptocurrency the customer paid in, so there was no conversion

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. Note:

The rate is locked for at most 1 hour after fixed_at, so for a payment request with a longer lifespan this is earlier than expires_at. In that case the customer must pay before valid_until.
At valid_until, the payment request ends: it gets the expired status if the customer created no transactions, and a partial payment is handled according to your underpayment handling rules.

Last modified on October 29, 2026

Reference

Deposits

Withdrawals

Payment requests

Exchanges

Currencies

Transactions

Account balance

System Health

Body