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",
      },
      "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:

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

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.