Listening for Payin Webhooks

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.

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.
data.originator.bankAccount.accountNumberFormat	The format of the account number of the originator.
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",
            "accountNumberFormat":"IBAN"
         }
      },
      "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"
         }
      }
   }
}