Listening for pay-in webhooks
In the previous guide, we discussed setting up a webhook listener. If you haven't configured your listener yet, please refer to that step to prepare for receiving webhooks.
Details on the data transmitted in webhooks are available Here.
Payment Flow Diagram and Webhooks Sent
Payment Complete Webhooks
Upon the end user successfully completing the payment within the allocated time frame and with the correct amount, you'll receive the following webhooks:
- transactionDetected: Issued when the transaction first appears on the blockchain. This may follow the processing status webhook, depending on blockchain network speeds.
- statusChanged - Processing: Dispatched when the payment status updates to processing after the transaction is recognized on the platform.
- transactionConfirmed: Sent once the transaction achieves the requisite number of confirmations on the blockchain.
- statusChanged - Complete: Issued when the payment status updates to complete following blockchain confirmation.
The statusChanged - Complete webhook delivers comprehensive payment details, including the final amounts sent (actual
fields) and the transaction hash within the transactions
array.
Payment Expired Webhooks
Should the end user fail to complete the payment within the designated time, you'll receive:
- statusChanged - Expired indicates the payment status has updated to expired due to elapsed expiry minutes without payment completion
When an end user does not complete the payment, the payment expires and only one webhook is sent out to let you know no transactions were detected within the given time frame.
Payment Exception Scenario Webhooks
Underpaid Webhooks
If the end user sends less cryptocurrency than required but within the expiry window, the following webhooks are triggered:
- transactionDetected: Notices the transaction on the blockchain, potentially after the processing status webhook.
- statusChanged - Processing: Updates the payment to processing status upon detecting the transaction.
- transactionConfirmed: Confirms the transaction once it meets the blockchain confirmation criteria.
- statusChanged - Underpaid: Marks the payment as underpaid after confirmation, noting the received amount is less than expected.
The statusChanged - Underpaid webhook details the received amount (actual
fields), allowing comparison with the expected amount (amount
fields).
Overpaid Webhooks
If the end user sends more cryptocurrency than required but within the expiry window, the following webhooks are triggered:
- transactionDetected: Issued when the transaction first appears on the blockchain. This may follow the processing status webhook, depending on blockchain network speeds.
- statusChanged - Processing: Dispatched when the payment status updates to processing after the transaction is recognized on the platform.
- transactionConfirmed: Sent once the transaction achieves the requisite number of confirmations on the blockchain.
- statusChanged - Complete: Issued when the payment status updates to complete following blockchain confirmation.
Note payments exceeding the expected amount within the expiry window, the sequence mirrors that of complete payments, with a notable distinction in the actual
field indicating a higher received amount
than expected. Always compare the actual
and amount
fields in the final webhook to identify overpayments.
Late or Duplicate Payment Webhooks
If the payment is detected or sent after the expiry webhook has been sent out, or if the end user sends an additional payment to the same payment links address, the following webhooks are triggered:
- statusChanged - Expired: Indicates payment expiration after the lapse of the expiry window without payment.
- transactionDetected: Detected transactions post-expiration are noted, possibly following the expiry notification.
- transactionConfirmed: Confirms late transactions upon achieving blockchain confirmation criteria.
- transactionLate: Issued for confirmed transactions beyond the expiry limit or for duplicate payments to the same wallet address.
The transactionLate
webhook specifies details for each late or duplicate payment. Multiple payments to the same address trigger this webhook, with a comprehensive list of transactions available in the transactionConfirmed
webhook.
Payment In Webhooks
{
"source": "payment",
"event": "transactionDetected",
"data": {
"uuid": "d993b0bc-dace-4742-81d8-6ae629dab063",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709895600000,
"expiryDate": 1709982000000,
"quoteExpiryDate": 1709982000000,
"acceptanceExpiryDate": 1709895667000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_0plkzH",
"type": "IN",
"subType": "merchantPayIn",
"status": "PENDING",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 0
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002764,
"actual": 0
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0?value=2.76415E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=d993b0bc-dace-4742-81d8-6ae629dab063&hpp=true",
"transactions": [
{
"dateCreated": 1709895679212,
"dateConfirmed": null,
"hash": "0x3d8ff17b4a2be304eff0ece0373f538f5e1a19e637652466c9ab15c599b6d91b",
"amount": 0,
"risk": null,
"networkFeeCurrency": "ETH",
"networkFeeAmount": null,
"sources": null,
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "statusChanged",
"data": {
"uuid": "d993b0bc-dace-4742-81d8-6ae629dab063",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709895600000,
"expiryDate": 1709982000000,
"quoteExpiryDate": 1709982000000,
"acceptanceExpiryDate": 1709895667000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_0plkzH",
"type": "IN",
"subType": "merchantPayIn",
"status": "PROCESSING",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 0
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002764,
"actual": 0
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0?value=2.76415E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=d993b0bc-dace-4742-81d8-6ae629dab063&hpp=true",
"transactions": [
{
"dateCreated": 1709895679212,
"dateConfirmed": null,
"hash": "0x3d8ff17b4a2be304eff0ece0373f538f5e1a19e637652466c9ab15c599b6d91b",
"amount": 0,
"risk": null,
"networkFeeCurrency": "ETH",
"networkFeeAmount": null,
"sources": null,
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "transactionConfirmed",
"data": {
"uuid": "d993b0bc-dace-4742-81d8-6ae629dab063",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709895600000,
"expiryDate": 1709982000000,
"quoteExpiryDate": 1709982000000,
"acceptanceExpiryDate": 1709895667000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_0plkzH",
"type": "IN",
"subType": "merchantPayIn",
"status": "PROCESSING",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 0
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0.00276415
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002764,
"actual": 0
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0?value=2.76415E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=d993b0bc-dace-4742-81d8-6ae629dab063&hpp=true",
"transactions": [
{
"dateCreated": 1709895679000,
"dateConfirmed": 1709895776194,
"hash": "0x3d8ff17b4a2be304eff0ece0373f538f5e1a19e637652466c9ab15c599b6d91b",
"amount": 0.00276415,
"risk": {
"level": "LOW",
"resourceName": null,
"resourceCategory": null,
"alerts": []
},
"networkFeeCurrency": "ETH",
"networkFeeAmount": 0.000033940950855,
"sources": [
"0x84a4a239805d06c685219801b82bea7c76702214"
],
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "statusChanged",
"data": {
"uuid": "d993b0bc-dace-4742-81d8-6ae629dab063",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709895600000,
"expiryDate": 1709982000000,
"quoteExpiryDate": 1709982000000,
"acceptanceExpiryDate": 1709895667000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_0plkzH",
"type": "IN",
"subType": "merchantPayIn",
"status": "COMPLETE",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 10
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0.00276415
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0.00276415
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002764,
"actual": 0.00002764
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0?value=2.76415E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=d993b0bc-dace-4742-81d8-6ae629dab063&hpp=true",
"transactions": [
{
"dateCreated": 1709895679000,
"dateConfirmed": 1709895776000,
"hash": "0x3d8ff17b4a2be304eff0ece0373f538f5e1a19e637652466c9ab15c599b6d91b",
"amount": 0.00276415,
"risk": {
"level": "LOW",
"resourceName": null,
"resourceCategory": null,
"alerts": []
},
"networkFeeCurrency": "ETH",
"networkFeeAmount": 0.00003394,
"sources": [
"0x84a4a239805d06c685219801b82bea7c76702214"
],
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "statusChanged",
"data": {
"uuid": "c11b0f66-2e7f-4ff0-9963-e485511ae49f",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709896743000,
"expiryDate": 1709896862203,
"quoteExpiryDate": null,
"acceptanceExpiryDate": null,
"quoteStatus": "TEMPLATE",
"reference": "test_reference_in_ewmnnj",
"type": "IN",
"subType": "merchantPayIn",
"status": "EXPIRED",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 0
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276456,
"actual": 0
},
"paidCurrency": {
"currency": null,
"amount": 0,
"actual": 0
},
"feeCurrency": {
"currency": "ETH",
"amount": 0,
"actual": 0
},
"displayRate": null,
"exchangeRate": null,
"address": null,
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=c11b0f66-2e7f-4ff0-9963-e485511ae49f&hpp=true",
"transactions": [],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "statusChanged",
"data": {
"uuid": "83e3287c-540e-4f43-8953-e5b2db646ca5",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709895979000,
"expiryDate": 1709982379000,
"quoteExpiryDate": 1709982379000,
"acceptanceExpiryDate": 1709896020000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_LGkyRO",
"type": "IN",
"subType": "merchantPayIn",
"status": "UNDERPAID",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 3.62
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276601,
"actual": 0.001
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.00276601,
"actual": 0.001
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002766,
"actual": 0.00001
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3615.315924382052
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xe4828053f59d310ee50984d0cd84b622cc03b19f",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xe4828053f59d310ee50984d0cd84b622cc03b19f?value=2.76601E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=83e3287c-540e-4f43-8953-e5b2db646ca5&hpp=true",
"transactions": [
{
"dateCreated": 1709896040000,
"dateConfirmed": 1709896133000,
"hash": "0xb8a33c20e4e0c6f747e87e1e632e9cdf22e62f0a99a18faefc7e327b85f8537d",
"amount": 0.001,
"risk": {
"level": "LOW",
"resourceName": null,
"resourceCategory": null,
"alerts": []
},
"networkFeeCurrency": "ETH",
"networkFeeAmount": 0.0000355,
"sources": [
"0x84a4a239805d06c685219801b82bea7c76702214"
],
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3615.315924382052
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "transactionLate",
"data": {
"uuid": "1401c32a-f8c1-49d9-a24c-5ae81b0ea2b3",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709897205000,
"expiryDate": 1709897284000,
"quoteExpiryDate": 1709897265000,
"acceptanceExpiryDate": 1709897245000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_d1plQ7",
"type": "IN",
"subType": "merchantPayIn",
"status": "EXPIRED",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 10
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.0027682,
"actual": 0.0027682
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.0027682,
"actual": 0.0027682
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002768,
"actual": 0.00002768
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3612.455747417094
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0x8c12686c4277ae7b48a2cf19256cc29ba2184bf5",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0x8c12686c4277ae7b48a2cf19256cc29ba2184bf5?value=2.7682E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=1401c32a-f8c1-49d9-a24c-5ae81b0ea2b3&hpp=true",
"transactions": [
{
"dateCreated": 1709897305000,
"dateConfirmed": 1709897394000,
"hash": "0x8aa160b0b175624b5381f100d9b9ffbff199e65c6e53335b596aee926d831b42",
"amount": 0.0027682,
"risk": {
"level": "LOW",
"resourceName": null,
"resourceCategory": null,
"alerts": []
},
"networkFeeCurrency": "ETH",
"networkFeeAmount": 0.00005765,
"sources": [
"0x84a4a239805d06c685219801b82bea7c76702214"
],
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3612.455747417094
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "transactionOnHold",
"data": {
"uuid": "b078499c-0c6c-4e3f-8a32-66dca1d2676b",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709543074000,
"expiryDate": 1709715874000,
"quoteExpiryDate": 1709715874000,
"acceptanceExpiryDate": 1709543139000,
"quoteStatus": "ACCEPTED",
"reference": "REF958403",
"type": "IN",
"subType": "merchantPayIn",
"status": "PROCESSING",
"displayCurrency": {
"currency": "ETH",
"amount": 0.01,
"actual": 0
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.01,
"actual": 0
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.01,
"actual": 0
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.0001,
"actual": 0
},
"displayRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xc643e89d9499d1e888c0be5c89b0d49973115d8a",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xc643e89d9499d1e888c0be5c89b0d49973115d8a?value=1E+16",
"alternatives": []
},
"returnUrl": "",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=b078499c-0c6c-4e3f-8a32-66dca1d2676b&hpp=true",
"transactions": [
{
"dateCreated": 1709543141000,
"dateConfirmed": null,
"hash": "0xfc403fb78ce3d05205c90ae91ddaf5f9760fd00ca15714b01951415ff3dbd172",
"amount": 0.01,
"risk": null,
"networkFeeCurrency": "ETH",
"networkFeeAmount": null,
"sources": null,
"displayRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": true
}
],
"refund": null,
"refunds": []
}
}
{
"source": "payment",
"event": "statusChanged",
"data": {
"uuid": "d993b0bc-dace-4742-81d8-6ae629dab063",
"merchantDisplayName": "ETH Merchant ",
"merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
"dateCreated": 1709895600000,
"expiryDate": 1709982000000,
"quoteExpiryDate": 1709982000000,
"acceptanceExpiryDate": 1709895667000,
"quoteStatus": "ACCEPTED",
"reference": "test_reference_in_0plkzH",
"type": "IN",
"subType": "merchantPayIn",
"status": "CANCELLED",
"displayCurrency": {
"currency": "EUR",
"amount": 10,
"actual": 10
},
"walletCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0.00276415
},
"paidCurrency": {
"currency": "ETH",
"amount": 0.00276415,
"actual": 0.00276415
},
"feeCurrency": {
"currency": "ETH",
"amount": 0.00002764,
"actual": 0.00002764
},
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"address": {
"address": "0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0",
"tag": null,
"protocol": "ETH",
"uri": "ethereum:0xc4d8b4b0e0601f49c88f41c4a9490f0d7f4ceed0?value=2.76415E+15",
"alternatives": []
},
"returnUrl": "https://www.your-url-here.com",
"redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=d993b0bc-dace-4742-81d8-6ae629dab063&hpp=true",
"transactions": [
{
"dateCreated": 1709895679000,
"dateConfirmed": 1709895776000,
"hash": "0x3d8ff17b4a2be304eff0ece0373f538f5e1a19e637652466c9ab15c599b6d91b",
"amount": 0.00276415,
"risk": {
"level": "LOW",
"resourceName": null,
"resourceCategory": null,
"alerts": []
},
"networkFeeCurrency": "ETH",
"networkFeeAmount": 0.00003394,
"sources": [
"0x84a4a239805d06c685219801b82bea7c76702214"
],
"displayRate": {
"base": "ETH",
"counter": "EUR",
"rate": 3617.748674999548
},
"exchangeRate": {
"base": "ETH",
"counter": "ETH",
"rate": 1
},
"protocol": "ETH",
"isOnHold": false
}
],
"refund": null,
"refunds": []
}
}
Updated 11 months ago