Listening for payment webhooks

📘
We covered how to create a webhook listener here in the getting setup guide - if you haven't done this already, go back to this step to get ready to receive webhooks.

Webhook Statuses

In the payment workflow you should expect to receive the following webhooks:

Event	Description
`transactionDetected`	The end-user has sent a payment and it has been detected on the blockchain but is not yet complete.
`statusChanged`	The status of the payment has changed, for instance, it may have changed from `pending` to `processing`, `pending` to `expired` or `processing` to `complete`.
`transactionConfirmed`	The payment the end-user sent has been confirmed on the blockchain and the funds will be credited to the merchant account once the cryptocurrency transaction gets the required number of confirmations on the network.
`transactionLate`	The end-user has sent funds to a payment that is already in an `expired`, `complete`, or `underpaid` state.
`transactionOnHold`	The payment has come from a high risk address and is held to be further analysed.

Webhook Examples

Some examples:

{
  "source": "payment",
  "event": "transactionDetected",
  "data": {
    "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b",
    "merchantDisplayName": "ethMerch",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010030000,
    "expiryDate": 1633011226000,
    "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6",
    "type": "IN",
    "status": "PENDING",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 10000,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 77.11,
      "actual": 0
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.0305817,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.77,
      "actual": 0
    },
    "displayRate": {
      "base": "ETH",
      "counter": "JPY",
      "rate": 326992.94022242059793929
    },
    "exchangeRate": {
      "base": "EUR",
      "counter": "ETH",
      "rate": 0.00073
    },
    "address": {
      "protocol": null,
      "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156",
      "tag": null
    },
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct",
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010179620,
        "dateConfirmed": null,
        "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea",
        "amount": 0,
        "risk": null,
        "networkFeeCurrency": null,
        "networkFeeAmount": null,
        "sources": null,
        "exchangeRate": null,
        "displayRate": null
      }
    ]
  }
}

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b",
    "merchantDisplayName": "ethMerch",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010030000,
    "expiryDate": 1633011226000,
    "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6",
    "type": "IN",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 10000,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 77.11,
      "actual": 0
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.0305817,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.77,
      "actual": 0
    },
    "displayRate": {
      "base": "ETH",
      "counter": "JPY",
      "rate": 326992.94022242059793929
    },
    "exchangeRate": {
      "base": "EUR",
      "counter": "ETH",
      "rate": 0.00073
    },
    "address": {
      "protocol": null,
      "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156",
      "tag": null
    },
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct",
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010179620,
        "dateConfirmed": null,
        "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea",
        "amount": 0,
        "risk": null,
        "networkFeeCurrency": null,
        "networkFeeAmount": null,
        "sources": null,
        "exchangeRate": null,
        "displayRate": null
      }
    ]
  }
}

{
  "source": "payment",
  "event": "transactionConfirmed",
  "data": {
    "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b",
    "merchantDisplayName": "ethMerch",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010030000,
    "expiryDate": 1633011226000,
    "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6",
    "type": "IN",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 10000,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 77.11,
      "actual": 0
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.0305817,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.77,
      "actual": 0
    },
    "displayRate": {
      "base": "ETH",
      "counter": "JPY",
      "rate": 326992.94022242059793929
    },
    "exchangeRate": {
      "base": "EUR",
      "counter": "ETH",
      "rate": 0.00073
    },
    "address": {
      "protocol": null,
      "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156",
      "tag": null
    },
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct",
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010180000,
        "dateConfirmed": 1633010241637,
        "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea",
        "amount": 0.0305817,
        "risk": {
          "level": "UNKNOWN",
          "resourceName": null,
          "resourceCategory": null
        },
        "networkFeeCurrency": "ETH",
        "networkFeeAmount": 0.000031500000252,
        "sources": [
          "0x1a2e97fd13c0610239c0b1cdbb0806f35adff3f0"
        ],
        "exchangeRate": {
          "base": "EUR",
          "counter": "ETH",
          "rate": 0.00073
        },
        "displayRate": {
          "base": "ETH",
          "counter": "JPY",
          "rate": 326992.9402224206
        }
      }
    ]
  }
}

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "5c75bc40-c1b2-4f57-b96f-79882a6e7c4b",
    "merchantDisplayName": "ethMerch",
    "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
    "dateCreated": 1633010030000,
    "expiryDate": 1633011226000,
    "reference": "c71102cf-4ac7-4503-8003-2e63931dd6e6",
    "type": "IN",
    "status": "COMPLETE",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 10000,
      "actual": 10000
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 77.11,
      "actual": 77.11
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.0305817,
      "actual": 0.0305817
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.77,
      "actual": 0.77
    },
    "displayRate": {
      "base": "ETH",
      "counter": "JPY",
      "rate": 326992.94022242059793929
    },
    "exchangeRate": {
      "base": "EUR",
      "counter": "ETH",
      "rate": 0.00073
    },
    "address": {
      "protocol": null,
      "address": "0x6115cfe64f3a8e4d974984a22a01936343bc8156",
      "tag": null
    },
    "redirectUrl": "https://business.sandbox.bvnk.com/payin?uuid=5c75bc40-c1b2-4f57-b96f-79882a6e7c4b&flow=direct",
    "returnUrl": "https://yourwebsitename.com",
    "transactions": [
      {
        "dateCreated": 1633010180000,
        "dateConfirmed": 1633010241637,
        "hash": "0x087bcfd76ae12d6116d35a442e51dfff99e77fbf8330be39017dbdc60df7afea",
        "amount": 0.0305817,
        "risk": {
          "level": "UNKNOWN",
          "resourceName": null,
          "resourceCategory": null
        },
        "networkFeeCurrency": "ETH",
        "networkFeeAmount": 0.000031500000252,
        "sources": [
          "0x1a2e97fd13c0610239c0b1cdbb0806f35adff3f0"
        ],
        "exchangeRate": {
          "base": "EUR",
          "counter": "ETH",
          "rate": 0.00073
        },
        "displayRate": {
          "base": "ETH",
          "counter": "JPY",
          "rate": 326992.9402224206
        }
      }
    ]
  }
}

{
  "source": "payment",
  "event": "transactionLate",
  "data": {
    "uuid": "9a990a06-205e-4968-b0ec-b5ebe471f544",
    "merchantDisplayName": "ethMerch",
    "merchantId": "9051a209-3aae-4230-9dfa-23365e1091ht",
    "dateCreated": 1675078349,
    "expiryDate": 1675078409,
    "quoteExpiryDate": 1675078409,
    "acceptanceExpiryDate": 1675078391,
    "quoteStatus": "ACCEPTED",
    "reference": "12345",
    "type": "IN",
    "subType": "merchantPayIn",
    "status": "EXPIRED",
    "displayCurrency": {
      "currency": "JPY",
      "amount": 10000,
      "actual": 10000
    },
    "walletCurrency": {
      "currency": "EUR",
      "amount": 41.09,
      "actual": 41.09
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.03,
      "actual": 0.03
    },
    "feeCurrency": {
      "currency": "EUR",
      "amount": 0.41,
      "actual": 0.41
    },
    "displayRate": {
      "base": "ETH",
      "counter": "JPY",
      "rate": 326992.940222420597939291
    },
    "exchangeRate": {
      "base": "EUR",
      "counter": "ETH",
      "rate": 0.00073
    },
    "address": {
      "address": "0x0bb01acd01d068fc367b5216d548hui3a27d23ef",
      "tag": null,
      "protocol": "ETH",
      "uri": "ethereum:0x0bb01acd01d068fc367b5216d548hui3a27d23ef?value=2E+16",
      "alternatives": []
    },
    "returnUrl": "https://yourwebsitename.com",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=9a990a06-205e-4968-b0ec-b5ebe471f561&mps=true",
    "transactions": [
      {
        "dateCreated": 1675087346,
        "dateConfirmed": 1675087435,
        "hash": "0xa76b2b68519804e2a4a0670c74d15282e10e30870864883bdf2de5ae1f2fa55a",
        "amount": 0.03,
        "risk": {
          "level": "LOW",
          "resourceName": "UNKNOWN",
          "resourceCategory": "UNKNOWN",
          "alerts": null
        },
        "networkFeeCurrency": "ETH",
        "networkFeeAmount": 0.00055213,
        "sources": [
          "0xc98b568684774623a2ca899987666b9321af36bb"
        ],
        "displayRate": {
          "base": "ETH",
          "counter": "JPY",
          "rate": 326992.940222420597939291
        },
        "exchangeRate": {
          "base": "EUR",
          "counter": "ETH",
          "rate": 0.00073
        }
      }
    ],
    "refund": null,
    "refunds": []
  }
}

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "e0f34ab3-1054-4562-a085-f12deed16c35",
    "merchantDisplayName": "ETH Merchant ",
    "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
    "dateCreated": 1707311542000,
    "expiryDate": 1707313342000,
    "quoteExpiryDate": 1707313342000,
    "acceptanceExpiryDate": 1707311593000,
    "quoteStatus": "ACCEPTED",
    "reference": "REF20838",
    "type": "IN",
    "subType": "merchantPayIn",
    "status": "CANCELLED",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "ETH",
      "amount": 0.00454452,
      "actual": 0
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.00454452,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "ETH",
      "amount": 0.00004545,
      "actual": 0
    },
    "displayRate": {
      "base": "ETH",
      "counter": "EUR",
      "rate": 2200.452413016116
    },
    "exchangeRate": {
      "base": "ETH",
      "counter": "ETH",
      "rate": 1
    },
    "address": {
      "address": "0xdba9db26d64fa229b6feeb87c976542f4bb8a7d1",
      "tag": null,
      "protocol": "ETH",
      "uri": "ethereum:0xdba9db26d64fa229b6feeb87c976542f4bb8a7d1?value=4.54452E+15",
      "alternatives": []
    },
    "returnUrl": "",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=e0f34ab3-1054-4562-a085-f12deed16c35&hpp=true",
    "transactions": [],
    "refund": null,
    "refunds": []
  }
}

{
    "source": "payment",
    "event": "statusChanged",
    "data": {
        "uuid": "e0f34ab3-1054-4562-a085-f12deed16c35",
        "merchantDisplayName": "ETH Merchant ",
        "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
        "dateCreated": 1707311542000,
        "expiryDate": 1707313342000,
        "quoteExpiryDate": null,
        "acceptanceExpiryDate": null,
        "quoteStatus": "TEMPLATE",
        "reference": "REF20838",
        "type": "IN",
        "subType": "merchantPayIn",
        "status": "EXPIRED",
        "displayCurrency": {
            "currency": "EUR",
            "amount": 10,
            "actual": 0
        },
        "walletCurrency": {
            "currency": "ETH",
            "amount": 0.00454452,
            "actual": 0
        },
        "paidCurrency": {
            "currency": null,
            "amount": 0,
            "actual": 0
        },
        "feeCurrency": {
            "currency": "ETH",
            "amount": 0.000045450,
            "actual": 0
        },
        "displayRate": null,
        "exchangeRate": null,
        "address": null,
        "returnUrl": "",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=e0f34ab3-1054-4562-a085-f12deed16c35",
        "transactions": [],
        "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": []
  }
}