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

Field

Description

event

Type of the event triggering the webhook.

eventId

Unique identifier for the event.

timestamp

Timestamp of when the event occurred.

data.status

Status of the payout:

  • PROCESSING

  • PENDING_APPROVAL

  • COMPLETED

  • CANCELLED

  • FAILED

  • RETURNED

data.customerReference

Customer-specific reference for the transaction. Optional.

data.transactionReference

Unique reference for the transaction generated by BVNK.

data.paymentReference

Reference description of the payment. The text is propagated along with the transfer, so a beneficiary could see it.

data.valueDate

Date the transaction was valued.

data.amount.value

Value of the transaction amount.

data.amount.currencyCode

Currency code of the transaction amount.

data.fee.value

Value of the transaction fee.

data.fee.currencyCode

Currency code of the transaction fee.

data.paymentMethod

Payment method used for the pay-in.

data.originator.name

Name of the sender, which can be a company or an individual.

data.originator.bankAccount.bankCode

Bank code of the sender. Optional.

data.originator.bankAccount.accountNumber

Account number of the sender. Optional.

data.originator.bankAccount.accountNumberFormat

Format of the account number of the sender.

data.originator.address.addressLine1

Originator's address line 1. Optional.

data.originator.address.addressLine2

Originator's address line 2. Optional.

data.originator.address.city

Sender's city. Optional.

data.originator.address.region

Sender's region or state. Optional.

data.originator.address.postCode

Sender's postal code. Optional.

data.originator.address.countryCode

Sender's country code. Optional.

data.originator.address.fullAddress

Sender's full concatenated address. Optional.

data.beneficiary.walletId

Wallet ID of the beneficiary.

data.beneficiary.entity.type

Type of the beneficiary (recipient) entity.

data.beneficiary.entity.name

Name of the beneficiary for companies.

data.beneficiary.entity.firstName

First name of the beneficiary for individuals.

data.beneficiary.entity.lastName

Last name of the beneficiary for individuals.

data.beneficiary.bankAccount.bankCode

Bank code of the beneficiary. Optional.

data.beneficiary.bankAccount.accountNumber

Account number of the beneficiary.

data.beneficiary.bankAccount.accountNumberFormat

Format of the account number of the beneficiary.

Webhook Example

{
   "event":"bvnk:payment:payin:status-change",
   "eventId":"4d9f2f80-7f4d-11ee-8c99-0242ac120002",
   "timestamp":"2024-10-28T12:25:21.716405000Z",
   "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"
         }
      }
   }
}