Payout Notifications

With the Payout webhook, you can send real-time notifications about key payout events, such as processing, completion, or failure, enabling automated updates without manual checks in your system.

To configure Payout webhooks, go to the BVNK Portal and navigate to Integrations > Webhooks. For the full guide, see Enable Webhooks for Fiat Payments.

Additionally, see a product demo of the Notification feature here and check more at the Help Centre.

Webhook Type

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

Event	Description
`bvnk:payment:payout:status-change`	Payout 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.
`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.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.

Webhook Example

{
   "event":"bvnk:payment:payout: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":{
         "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"
        }
    }
   }
}