Listen for 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.

Payouts ver. 2

You can expect the following event to be triggered for payouts ver.2:

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

{
  "event": "payment:v2:payout:status-change",
  "eventId": "0199997f-83b2-7497-aefd-f729a1553078",
  "timestamp": "2025-09-30T07:21:34.898303644Z",
  "data": {
    "id": "f5a879ec-9dcd-11f0-95d7-89347b196078",
    "fees": {
      "processingFee": {
        "amount": 0.12,
        "currency": "EUR"
      },
      "customerFee": {
        "amount": 0.12,
        "currency": "EUR"
      }
    },
    "type": "payment:v2:payout:status-change",
    "method": "SEPA_INST",
    "status": "PROCESSING",
    "createdAt": "2025-09-30T07:20:36.380343Z",
    "direction": "OUT",
    "updatedAt": "2025-09-30T07:20:36.385497Z",
    "originator": {
      "amount": 7,
      "customerId": "ac7ce72f-8271-44b5-93ce-d1865f27b0bb",
      "entity": {
        "type": "COMPANY",
        "legalName": "BVNK Virtual Accounts"
      },
      "currency": "EUR",
      "walletId": "a:23112847683858:B4jXNDk:1"
    },
    "beneficiary": {
      "amount": 7,
      "entity": {
        "type": "INDIVIDUAL",
        "address": {
          "city": "New York",
          "region": "NY",
          "country": "US",
          "postCode": "10001",
          "addressLine1": "123 Business Park",
          "addressLine2": "Suite 456"
        },
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-09-30T07:20:36.385497Z",
        "relationshipType": "SELF_OWNED"
      },
      "currency": "EUR",
      "bankAccount": {
        "bank": {
          "nid": "12345345",
          "address": {
            "city": "New York",
            "region": "NY",
            "country": "US",
            "postCode": "10017",
            "addressLine1": "JP Morgan Chase Bank",
            "addressLine2": "270 Park Avenue"
          },
          "identificationCode": "SYPLMTM2XXX"
        },
        "accountNumber": "MT17SYPL39480094112231274874660",
      },
      "remittanceInformation": "FIRST TEST SUCCESSFUL"
    }
  },
  "metadata": {
    "someKey": "someValue"
  }
}

Field	Description
`event`	Type of the event triggering the webhook.
`eventId`	Unique identifier for the event.
`timestamp`	Timestamp of when the event occurred.
`data.id`	Unique identifier for the payout transaction.
`data.fees.processingFee.amount`	Amount of the processing fee.
`data.fees.processingFee.currency`	Currency code of the processing fee.
`data.fees.customerFee.amount`	Amount of the customer fee.
`data.fees.customerFee.currency`	Currency code of the customer fee.
`data.type`	Type of the payment event.
`data.method`	Payment method used for the payout. Possible values: `CRYPTO` (Only for crypto payouts. Not applicable to fiat) `WALLET` `CARD` (Only for crypto payouts. Not applicable to fiat) `SEPA_CT` `SEPA_INST` `CHAPS` `FASTER_PAYMENT` `SWIFT` `ACH` `ACH_SAME_DAY` `FEDWIRE` `FEDNOW` `RTP` `BOOK` `UNKNOWN`
`data.status`	Status of the payout. Possible values: `PENDING` `PROCESSING` `PENDING_APPROVAL` `ON_HOLD` `COMPLETED` `EXPIRED` `CANCELLED` `FAILED` `RETURNED`
`data.createdAt`	Timestamp when the payout was created.
`data.direction`	Direction of the payment: incoming (IN) or outgoing (OUT).
`data.updatedAt`	Timestamp when the payout was last updated.
`data.originator.amount`	Amount sent by the originator.
`data.originator.customerId`	Unique identifier of the customer.
`data.originator.entity.type`	Type of the sender entity.
`data.originator.entity.legalName`	Legal name of the sender entity.
`data.originator.currency`	Currency code of the originator amount.
`data.originator.walletId`	Wallet ID of the originator.
`data.beneficiary.amount`	Amount received by the beneficiary.
`data.beneficiary.entity.type`	Type of the beneficiary entity.
`data.beneficiary.entity.address.city`	City of the beneficiary's address.
`data.beneficiary.entity.address.region`	Region/state of the beneficiary's address.
`data.beneficiary.entity.address.country`	Country code of the beneficiary's address.
`data.beneficiary.entity.address.postCode`	Postal code of the beneficiary's address.
`data.beneficiary.entity.address.addressLine1`	First line of the beneficiary's address.
`data.beneficiary.entity.address.addressLine2`	Second line of the beneficiary's address.
`data.beneficiary.entity.firstName`	First name of the beneficiary for individuals.
`data.beneficiary.entity.lastName`	Last name of the beneficiary for individuals.
`data.beneficiary.entity.dateOfBirth`	Date of birth of the beneficiary.
`data.beneficiary.entity.relationshipType`	Relationship type of the beneficiary.
`data.beneficiary.currency`	Currency code of the beneficiary amount.
`data.beneficiary.bankAccount.bank.nid`	National identifier of the beneficiary's bank.
`data.beneficiary.bankAccount.bank.address.city`	City of the bank's address.
`data.beneficiary.bankAccount.bank.address.region`	Region/state of the bank's address.
`data.beneficiary.bankAccount.bank.address.country`	Country code of the bank's address.
`data.beneficiary.bankAccount.bank.address.postCode`	Postal code of the bank's address.
`data.beneficiary.bankAccount.bank.address.addressLine1`	First line of the bank's address.
`data.beneficiary.bankAccount.bank.address.addressLine2`	Second line of the bank's address.
`data.beneficiary.bankAccount.bank.identificationCode`	Bank identification code (BIC/SWIFT).
`data.beneficiary.bankAccount.accountNumber`	Account number of the beneficiary.
`data.beneficiary.remittanceInformation`	Additional information for the payment.
`metadata`	Additional metadata associated with the webhook event.

Payouts ver. 1

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.

{
   "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.