Step 5: Payins Notificiations

A payin webhook delivers real-time notifications to your system about key payin events, such as initiation, completion, or failure, ensuring automated updates without manual polling.

Payout Webhooks can be configured through the Integrations Channel in the BVNK Portal. This process is explained in the separate page .

You can access a product demo of the Notification feature here and read more on the Help Centre article.

Webhook Types

Once you have a vIBAN, and it recieves a deposit, the following webhooks will be sent out:

Event	Description
`bvnk:payment:payin:status-change`	The pay in has transitioned to a new state.

Data Types

Field	Description
event	The type of event triggering the webhook.
eventId	A unique identifier for the event.
timestamp	The timestamp of when the event occurred.
data.status	The status of the pay-in.
data.customerReference	A customer-specific reference for the transaction (optional).
data.transactionReference	A unique reference for the transaction.
data.paymentReference	A reference code for the payment.
data.valueDate	The date the transaction was valued.
data.amount.value	The value of the transaction amount.
data.amount.currencyCode	The currency code of the transaction amount.
data.fee.value	The value of the transaction fee.
data.fee.currencyCode	The currency code of the transaction fee.
data.paymentMethod	The payment method used for the pay-in.
data.originator.name	The name of the originator, which could be a company or an individual.
data.originator.bankAccount.bankCode	The bank code of the originator (optional).
data.originator.bankAccount.accountNumber	The account number of the originator (optional).
data.originator.bankAccount.accountNumberFormat	The format of the account number of the originator.
data.originator.address.addressLine1	Originator's address line 1 (optional).
data.originator.address.addressLine2	Originator's address line 2 (optional).
data.originator.address.city	Originator's city (optional).
data.originator.address.region	Originator's region or state (optional).
data.originator.address.postCode	Originator's postal code (optional).
data.originator.address.countryCode	Originator's country code (optional).
data.originator.address.fullAddress	Originator's full concatenated address (optional).
data.beneficiary.walletId	The wallet ID of the beneficiary.
data.beneficiary.entity.type	The type of beneficiary entity.
data.beneficiary.entity.name	The name of the beneficiary (for companies).
data.beneficiary.entity.firstName	The first name of the beneficiary (for individuals).
data.beneficiary.entity.lastName	The last name of the beneficiary (for individuals).
data.beneficiary.bankAccount.bankCode	The bank code of the beneficiary (optional).
data.beneficiary.bankAccount.accountNumber	The account number of the beneficiary.
data.beneficiary.bankAccount.accountNumberFormat	The format of the account number of the beneficiary.

Webhook Examples

For example:

{
   "event":"bvnk:payment:payin:status-change",
   "eventId":"4d9f2f80-7f4d-11ee-8c99-0242ac120002",
   "timestamp":"2024-10-28 09:25:21.716405",
   "data":{
      "status":"COMPLETED",
      "customerReference":"fd808a48-7313-4773-8383-fffb62fdc2d7",  //optional
      "transactionReference":"fd808a48-7313-4773-8383-fffb62fdc2d7",
      "paymentReference":"GBPCLEAREXTERNALPA",
      "valueDate":"2024-09-12",
      "amount":{
         "value":39,
         "currencyCode":"EUR"
      },
      "fee":{
         "value":3,
         "currencyCode":"EUR"
      },
      "paymentMethod":"SEPA_CT",
      "originator":{
         "name":"Some Business",
         "bankAccount":{
            "bankCode":"SAPYGB2L",  //optional
            "accountNumber":"GB93SAPY60838220490275", //optional
            "accountNumberFormat":"IBAN"
         },
         "address": {
            "addressLine1": "123 Main St",
            "addressLine2": "Apt 4B",
            "city": "London",
            "region": "London",
            "postCode": "12345",
            "countryCode", "GB",
            "fullAddress": "123 Main St, Apt 4B, London, London, 12345, GB"
         },
      },
      "beneficiary":{
         "walletId":"a:24042240678622:beEODVM:1",
         "entity":{
            "type":"COMPANY",
            "name":"Some Business",  //for company
            "firstName":"John", //for individual
            "lastName":"Doe", //for individual
         },
         "bankAccount":{
            "bankCode":"LHVBEE20",
            "accountNumber":"EE307777000028295451",
            "accountNumberFormat":"IBAN"
         }
      },
      "metadata": {
         "someKey": "someValue",
         "someKey2": {
            "someKey3": "someValue3"
         }
      }
   }
}