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 Types

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

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

Data Types

Field	Description
event	The type of event triggering the webhook.
eventId	A unique identifier for the event.
timestamp	The timestamp of when the event occurred.
data.status	The status of the payout.
data.customerReference	A customer-specific reference for the transaction (optional).
data.transactionReference	A unique reference for the transaction.
data.paymentReference	A reference code for the payment.
data.valueDate	The date the transaction was valued.
data.amount.value	The value of the transaction amount.
data.amount.currencyCode	The currency code of the transaction amount.
data.fee.value	The value of the transaction fee.
data.fee.currencyCode	The currency code of the transaction fee.
data.paymentMethod	The payment method used for the payout.
data.originator.walletId	The wallet ID of the originator.
data.originator.entity.type	The type of originator entity.
data.originator.entity.name	The name of the originator (for companies).
data.originator.entity.firstName	The first name of the originator (for individuals).
data.originator.entity.lastName	The last name of the originator (for individuals).
data.originator.bankAccount.bankCode	The bank code of the originator (optional).
data.originator.bankAccount.accountNumber	The account number of the originator.
data.originator.bankAccount.accountNumberFormat	The format of the account number of the originator.
data.beneficiary.entity.type	The type of beneficiary entity.
data.beneficiary.entity.name	The name of the beneficiary (for companies).
data.beneficiary.entity.firstName	The first name of the beneficiary (for individuals).
data.beneficiary.entity.lastName	The last name of the beneficiary (for individuals).
data.beneficiary.bankAccount.bankCode	The bank code of the beneficiary (optional).
data.beneficiary.bankAccount.accountNumber	The account number of the beneficiary.
data.beneficiary.bankAccount.accountNumberFormat	The format of the account number of the beneficiary.

Webhook Examples

For 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"
        }
    }
   }
}