Processing payment request callbacks
Payment request callbacks are sent whenever the status of a payment request changes. When you receive a callback with"status": "paid", the payment request has been successfully paid and can be treated as completed on your side.
Use foreign_id to identify the payment request or order in your system and map it to the user for whom the payment request was created.
Payment request callback payload examples
- Exchange rate is fixed
- A new transaction is detected
- Payment request paid
- Payment request failed
- Payment request expired (without a fixed rate)
- Payment request expired (with a fixed rate)
- Late payment received
- Payment request restricted
Sent when the payment request is created with a fixed exchange rate and is waiting for payment. At this stage, no funds have been received yet.
{
"payment_request_id": "019c0ebf-81e5-751d-aa57-fb9e2cba23c2",
"foreign_id": "order_12345",
"type": "payment_request",
"status": "processing",
"end_user_email": "[email protected]",
"payment_request_address": {
"id": "019c0ebf-84a1-7bdc-a09c-8b62294cc75d",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"convert_to": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
},
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"currency_sent": {
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"expected_amount": "0.0094",
"received_amount": "0",
"remaining_amount": "0.0094"
},
"fixed_at": 1769773958,
"expires_at": 1769774157,
"valid_until": 1769774157
}
Sent when a new payment transaction is detected for the payment request. The payment request remains in
processing status until the full required amount is received.{
"payment_request_id": "019c0f25-e7db-7ca3-b19f-a7916b5a4905",
"foreign_id": "order_34567",
"type": "payment_request",
"status": "processing",
"end_user_email": "[email protected]",
"payment_request_address": {
"id": "019c0f25-eb0d-70bd-b282-8e58de5d1b7c",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"convert_to": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "0x114da762447ccb464ac29134B2930e0570139F83"
},
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"currency_sent": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"expected_amount": "0.3",
"received_amount": "0.15",
"remaining_amount": "0.15"
},
"transactions": [
{
"id": "019c0f26-25fc-7738-bdf1-85708ec6e67c",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "0x114da762447ccb464ac29134B2930e0570139F83",
"amount": "0.15",
"txid": "0x12882dbbd810304bd0d9707472dbb40f8c2f7d9a1e6b3c4d5f60718293a4b5c6",
"status": "confirmed",
"late_payment": false
}
],
"fixed_at": 1769780669,
"expires_at": 1769780868,
"valid_until": 1769780868
}
Sent when the full required amount has been received and the payment request is successfully completed.
{
"payment_request_id": "019c0f25-e7db-7ca3-b19f-a7916b5a4905",
"foreign_id": "order_34567",
"type": "payment_request",
"status": "paid",
"end_user_email": "[email protected]",
"payment_request_address": {
"id": "019c0f25-eb0d-70bd-b282-8e58de5d1b7c",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"convert_to": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "0x114da762447ccb464ac29134B2930e0570139F83"
},
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"currency_sent": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"expected_amount": "0.3",
"received_amount": "0.3",
"remaining_amount": "0"
},
"currency_received": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"transactions": [
{
"id": "019c0f26-25fc-7738-bdf1-85708ec6e67c",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "0x114da762447ccb464ac29134B2930e0570139F83",
"amount": "0.15",
"txid": "0xa3f1c9d8427e6b5c1098d7e6f5a4b3c291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"status": "confirmed",
"late_payment": false
},
{
"id": "6425cf81-da66-4c60-8a53-6dbdf118ce09",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "0x114da762447ccb464ac29134B2930e0570139F83",
"amount": "0.15",
"txid": "0x12882dbbd810304bd0d9707472dbb40f8c2f7d9a1e6b3c4d5f60718293a4b5c6",
"status": "confirmed",
"late_payment": false
}
],
"fees": [
{
"type": "transfer_fee",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.00007808"
},
{
"type": "fee_payment_request_crypto",
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.00854354"
}
],
"fixed_at": 1769780669,
"expires_at": 1769780868,
"valid_until": 1769780868
}
Sent when the payment request is not successfully completed before expiry. Use the transaction details and amounts to understand what was received.
{
"payment_request_id": "019c0de8-4576-7e4f-85c7-43a5cb5e9f2d",
"foreign_id": "order_82652.32794293783",
"type": "payment_request",
"status": "failed",
"end_user_email": "[email protected]",
"payment_request_address": {
"id": "019c0de8-49df-762a-9705-4c304627dfd0",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"convert_to": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
},
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"currency_sent": {
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"expected_amount": "0.0094",
"received_amount": "0.009",
"remaining_amount": "0.0004"
},
"transactions": [
{
"id": "019c0de8-54a3-7163-b59c-95f38d982a31",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je",
"txid": "cf3c308839d67ab6bce3b2f275fcc197c5c19dc208efc35dbc0a68ff355d78e3",
"amount": "0.009",
"status": "confirmed",
"late_payment": false
}
],
"fixed_at": 1769759853,
"expires_at": 1769760051,
"valid_until": 1769760051
}
Sent when the payment request expires before payment is received and no fixed exchange rate was locked for the request.
{
"payment_request_id": "019bea8c-7d69-7632-8472-77443ac78a17",
"foreign_id": "order_85566.25193543735",
"type": "payment_request",
"status": "expired",
"end_user_email": "[email protected]",
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"expires_at": 1769166664
}
Sent when the payment request expires after a fixed exchange rate was locked, but no sufficient payment was received before expiry.
{
"payment_request_id": "019c0ebf-81e5-751d-aa57-fb9e2cba23c2",
"foreign_id": "order_12345",
"type": "payment_request",
"status": "expired",
"end_user_email": "[email protected]",
"payment_request_address": {
"id": "019c0ebf-84a1-7bdc-a09c-8b62294cc75d",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"convert_to": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
},
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"currency_sent": {
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"expected_amount": "0.0094",
"received_amount": "0",
"remaining_amount": "0.0094"
},
"fixed_at": 1769773958,
"expires_at": 1769774157,
"valid_until": 1769774157
}
Sent when a payment is received after the payment request has already expired or failed. Such transactions are marked with
late_payment: true.{
"payment_request_id": "019c0de8-4576-7e4f-85c7-43a5cb5e9f2d",
"foreign_id": "order_82652.32794293783",
"type": "payment_request",
"status": "failed",
"end_user_email": "[email protected]",
"payment_request_address": {
"id": "019c0de8-49df-762a-9705-4c304627dfd0",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"convert_to": {
"iso": "ETH",
"network_name": "ethereum"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
},
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"currency_sent": {
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"expected_amount": "0.0094",
"received_amount": "0.009",
"remaining_amount": "0.0004"
},
"transactions": [
{
"id": "019c0de8-54a3-7163-b59c-95f38d982a31",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je",
"txid": "cf3c308839d67ab6bce3b2f275fcc197c5c19dc208efc35dbc0a68ff355d78e3",
"amount": "0.009",
"status": "confirmed",
"late_payment": false
},
{
"id": "019c0de8-54a3-7163-b59c-95f38d982a32",
"currency": {
"iso": "BTC",
"network_name": "bitcoin"
},
"address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je",
"txid": "9b7f2a0c6d3e4f1a8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d",
"amount": "0.0004",
"status": "confirmed",
"late_payment": true
}
],
"fixed_at": 1769759853,
"expires_at": 1769760051,
"valid_until": 1769760051
}
Sent when the payer is not allowed to complete the payment.
{
"payment_request_id": "019c0de8-4576-7e4f-85c7-43a5cb5e9f2d",
"foreign_id": "order_82652.32794293783",
"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",
"end_user_reference": "account_14578",
"payment_request_amount": {
"currency": {
"iso": "ETH",
"network_name": "ethereum"
},
"amount": "0.3"
},
"expires_at": 1769166664
}