foreign_id to map the callback to a specific customer or order in your system.
- Successful flow
- Expired
- Failed for other reasons
A successful scenario involves at least three callbacks at various points.
- Rate fixed (
processingstatus) — sent when the user clicks Proceed to payment, or immediately for a fixed payment request. - Transaction detected (
processingstatus) — sent when a new payment transaction is detected for the payment request. May be sent multiple times if the customer makes multiple transactions. - Paid (
paidstatus) — sent when the correct amount of funds has been received, and the transactions got the required amount of network confirmations. The received amount may be slightly less than the full requested amount, according to your underpayment handling settings. Any subsequent incoming transaction will cause a Late payment callback.
{
"payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
"foreign_id": "order_12345",
"type": "payment_request",
"status": "processing",
"end_user_email": "[email protected]",
"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]",
"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": "0",
"received_amount": "115.99"
},
"transactions": [
{
"id": "019fd90e-8fda-737a-bf62-3e76ad244a8d",
"currency": {
"iso": "USDC",
"network_name": "ethereum"
},
"address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1",
"amount": "115.99",
"txid": "0x2b30fdf21cd15daddbc24e548ffbdc89f6d69849d80c953259051f904c9b201f",
"status": "verifying",
"late_payment": false
}
],
"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": "paid",
"end_user_email": "[email protected]",
"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": "0",
"received_amount": "115.99"
},
"currency_received": {
"currency": {
"iso": "EUR"
},
"amount": "100"
},
"transactions": [
{
"id": "019fd90e-8fda-737a-bf62-3e76ad244a8d",
"currency": {
"iso": "USDC",
"network_name": "ethereum"
},
"address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1",
"amount": "115.99",
"txid": "0x2b30fdf21cd15daddbc24e548ffbdc89f6d69849d80c953259051f904c9b201f",
"status": "confirmed",
"late_payment": false
}
],
"fees": [
{
"type": "fee_payment_request_crypto_to_fiat",
"currency": {
"iso": "EUR"
},
"amount": "1.5"
}
],
"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": "paid",
"end_user_email": "[email protected]",
"status_reason": "Underpayment accepted according to your payment handling rules",
"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": "0",
"received_amount": "115"
},
"currency_received": {
"currency": {
"iso": "EUR"
},
"amount": "99.15"
},
"transactions": [
{
"id": "019fd90e-8fda-737a-bf62-3e76ad244a8d",
"currency": {
"iso": "USDC",
"network_name": "ethereum"
},
"address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1",
"amount": "115",
"txid": "0x2b30fdf21cd15daddbc24e548ffbdc89f6d69849d80c953259051f904c9b201f",
"status": "confirmed",
"late_payment": false
}
],
"fees": [
{
"type": "fee_payment_request_crypto_to_fiat",
"currency": {
"iso": "EUR"
},
"amount": "1.5"
}
],
"expires_at": 1786023178,
"fixed_at": 1786022886,
"valid_until": 1786023178
}
If the customer hasn’t created any transactions during the lifespan or rate lock period, you will receive a callback with the
expired status. Any subsequent incoming transaction will cause a Late payment callback.{
"payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
"foreign_id": "order_12345",
"type": "payment_request",
"status": "expired",
"end_user_email": "[email protected]",
"payment_request_amount": {
"currency": {
"iso": "EUR"
},
"amount": "100"
},
"expires_at": 1786023178
}
{
"payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
"foreign_id": "order_12345",
"type": "payment_request",
"status": "expired",
"end_user_email": "[email protected]",
"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": "expired",
"end_user_email": "[email protected]",
"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"
},
"transactions": [
{
"id": "019fd90e-8fda-737a-bf62-3e76ad244a8d",
"currency": {
"iso": "USDC",
"network_name": "ethereum"
},
"address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1",
"amount": "115.99",
"txid": "0x2b30fdf21cd15daddbc24e548ffbdc89f6d69849d80c953259051f904c9b201f",
"status": "confirmed",
"late_payment": true
}
],
"expires_at": 1786023178,
"fixed_at": 1786022886,
"valid_until": 1786023178
}
If the payment request was not fully paid in time, you will receive a callback with the
failed status. Possible reasons include:- Underpayment — the customer sent a smaller amount than required, and the lifespan already ended. Any subsequent incoming transaction will cause a Late payment callback. Note that you can configure underpayments handling.
- Unconfirmed transaction — one or more transactions did not get the required amount of network confirmations before the payment request expired.
- Invalid transaction — the transactions were canceled in the blockchain or were smaller than the minimum deposit amount. Note that invalid transactions are not included in the callback.
- Payment restricted — the payment can not be processed due to internal restrictions.
{
"payment_request_id": "019fd737-361e-7ea2-ae63-da064e163582",
"foreign_id": "order_12345",
"type": "payment_request",
"status": "failed",
"end_user_email": "[email protected]",
"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": "65.99",
"received_amount": "50"
},
"transactions": [
{
"id": "019fd90e-8fda-737a-bf62-3e76ad244a8d",
"currency": {
"iso": "USDC",
"network_name": "ethereum"
},
"address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1",
"amount": "50",
"txid": "0x2b30fdf21cd15daddbc24e548ffbdc89f6d69849d80c953259051f904c9b201f",
"status": "confirmed",
"late_payment": false
}
],
"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": "failed",
"end_user_email": "[email protected]",
"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"
},
"transactions": [
{
"id": "019fd90e-8fda-737a-bf62-3e76ad244a8d",
"currency": {
"iso": "USDC",
"network_name": "ethereum"
},
"address": "0x6b83306B975059a1d3b2693C31f675bDb9863Af1",
"amount": "115.99",
"txid": "0x2b30fdf21cd15daddbc24e548ffbdc89f6d69849d80c953259051f904c9b201f",
"status": "not_confirmed",
"late_payment": false
}
],
"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": "failed",
"end_user_email": "[email protected]",
"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": "failed",
"end_user_email": "[email protected]",
"status_reason": "Service is restricted for the payer. Payments from this payer cannot be processed",
"payment_request_amount": {
"currency": {
"iso": "EUR"
},
"amount": "100"
},
"expires_at": 1786023178
}