Enable Pay-in Notifications

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

Webhook Type

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

EventDescription
bvnk:payment:payin:status-changeThe pay-in has transitioned to a new state.

Data Types

FieldDescription
eventType of the event triggering the webhook.
eventIdUnique identifier for the event.
timestampTimestamp of when the event occurred.
data.statusStatus of the pay-in.
data.customerReferenceCustomer-specific reference for the transaction. Optional.
data.transactionReferenceUnique reference for the transaction.
data.paymentReferenceReference code for the payment.
data.valueDateDate the transaction was valued.
data.amount.valueValue of the transaction amount.
data.amount.currencyCodeCurrency code of the transaction amount.
data.fee.valueValue of the transaction fee.
data.fee.currencyCodeCurrency code of the transaction fee.
data.paymentMethodPayment method used for the pay-in.
data.originator.nameName of the sender, which can be a company or an individual.
data.originator.bankAccount.bankCodeBank code of the sender. Optional.
data.originator.bankAccount.accountNumberAccount number of the sender. Optional.
data.originator.bankAccount.accountNumberFormatFormat of the account number of the sender.
data.originator.address.addressLine1Originator's address line 1. Optional.
data.originator.address.addressLine2Originator's address line 2. Optional.
data.originator.address.citySender's city. Optional.
data.originator.address.regionSender's region or state. Optional.
data.originator.address.postCodeSender's postal code. Optional.
data.originator.address.countryCodeSender's country code. Optional.
data.originator.address.fullAddressSender's full concatenated address. Optional.
data.beneficiary.walletIdWallet ID of the beneficiary.
data.beneficiary.entity.typeType of the beneficiary (recipient) entity.
data.beneficiary.entity.nameName of the beneficiary for companies.
data.beneficiary.entity.firstNameFirst name of the beneficiary for individuals.
data.beneficiary.entity.lastNameLast name of the beneficiary for individuals.
data.beneficiary.bankAccount.bankCodeBank code of the beneficiary. Optional.
data.beneficiary.bankAccount.accountNumberAccount number of the beneficiary.
data.beneficiary.bankAccount.accountNumberFormatFormat of the account number of the beneficiary.

Webhook 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",  // This will be received for embedded and nested use cases
      "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"
         }
      }
   }
}