Listening for Internal Transfer Webhooks

An internal transfer webhook sends real-time notifications to your system about key internal transfer events between Principle and Underlying wallets, such as initiation, completion, or failure, enabling automated updates without manual intervention.

Webhook Type

In the internal transfer workflow you should expect to receive the following webhooks:

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

Data Types

Field	Description
`event`	Type of event triggering the webhook.
`eventId`	Unique identifier for the event.
`timestamp`	Timestamp of when the event occurred.
`data.status`	Status of the transfer.
`data.customerReference`	Customer-specific reference for the transaction. Optional.
`data.transactionReference`	Unique reference for the transaction.
`data.paymentReference`	Reference code for the payment.
`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.originator.walletId`	Wallet ID of the sender / originator.
`data.originator.accountReference`	Unique reference for the account of the sender.
`data.originator.entity.type`	Type of the sender entity. Possible values: `INDIVIDUAL` `COMPANY`
`data.originator.entity.name`	Name of the sender for companies.
`data.originator.entity.firstName`	First name of the sender for individuals.
`data.originator.entity.lastName`	Last name of the sender for individuals.
`data.beneficiary.walletId`	Wallet ID of the beneficiary (recipient).
`data.beneficiary.accountReference`	Unique reference for the account of the beneficiary.
`data.beneficiary.entity.type`	Type of beneficiary 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.

Webhook Example

{
   "event": "bvnk:payment:transfer:status-change",
   "eventId": "0193ba8c-74f4-7bd3-a2fb-00e43851577c",
   "timestamp": "2024-12-12T11:06:27.444216650Z",
   "data": {
      "fee": {
         "value": 0,
         "currencyCode": "EUR"
       },
      "amount": {
         "value": 10,
         "currencyCode": "EUR"
      },
      "status": "COMPLETED",
      "valueDate": "2024-12-12",
      "originator": {
         "entity": {
            "type": "INDIVIDUAL",
            "lastName": "John",
            "firstName": "Doe"
         },
         "walletId": "a:24103136208222:wSFXcWf:1",
         "accountReference": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea"
      },
      "beneficiary": {
         "entity": {
            "name": "Test Ltd",
            "type": "COMPANY"
         },
         "walletId": "a:24082935226274:do8hboJ:1",
         "accountReference": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea"
      },
      "paymentReference": "REF124903",
      "transactionReference": "13584355-b879-11ef-982c-e1c33615f5a8"
   }
}

Updated about 1 month ago