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:

EventDescription
payment:v2:payout:status-changePayout 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",
        "intermediaryBanks": [],
        "accountNumberFormat": "IBAN"
      },
      "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.bankAccount.intermediaryBanks

List of intermediary banks involved in the transaction.

data.beneficiary.bankAccount.accountNumberFormat

Format of the 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:

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