Enable Payout Notifications

This guide will allow you to enable a payout webhook. With it, you can sends real-time notifications to your system about key payout events, such as processing, completion, or failure, enabling automated updates without manual checks.

In the payout workflow, you should expect to receive the following webhook:

EventDescription
bvnk:payment:payout:status-changePayout has transitioned to a new state.
{
   "event":"bvnk:payment:payout: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":{
         "walletId":"a:24011842467367:OqdNqVa:1",
         "entity":{
            "type":"COMPANY",
            "name":"Some Business",  //for company
            "firstName":"John", //for individual
            "lastName":"Doe", //for individual
         },
         "bankAccount":{
            "bankCode":"SAPYGB2L",  //optional
            "accountNumber":"GB93SAPY60838220490275",
            "accountNumberFormat":"IBAN"
         }
      },
      "beneficiary":{
         "entity":{
            "type":"COMPANY",
            "name":"Some Business",  //for company
            "firstName":"John", //for individual
            "lastName":"Doe", //for individual
         },
         "bankAccount":{
            "bankCode":"SAPYGB2L",  //optional
            "accountNumber":"GB93SAPY60838220562249",
            "accountNumberFormat":"IBAN"
         }
      },
      "metadata": {
        "someKey": "someValue",
        "someKey2": {
            "someKey3": "someValue3"
        }
    }
   }
}

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 payout.

data.originator.walletId

Wallet ID of the sender / originator.

data.originator.entity.type

Type of the sender entity.

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.originator.bankAccount.bankCode

Bank code of the sender. Optional.

data.originator.bankAccount.accountNumber

Account number of the sender.

data.originator.bankAccount.accountNumberFormat

Format of the account number of the sender.

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.