Payout Notifications

The following guide describes how to enable payout webhook.

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:

EventDescription
bvnk:payment:payout:status-changePayout 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 payout.
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 payout.
data.originator.walletIdWallet ID of the sender / originator.
data.originator.entity.typeType of the sender entity.
data.originator.entity.nameName of the sender for companies.
data.originator.entity.firstNameFirst name of the sender for individuals.
data.originator.entity.lastNameLast name of the sender for individuals.
data.originator.bankAccount.bankCodeBank code of the sender. Optional.
data.originator.bankAccount.accountNumberAccount number of the sender.
data.originator.bankAccount.accountNumberFormatFormat of the account number of the sender.
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: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"
        }
    }
   }
}