Enable Wallet Creation Notifications

A wallet creation webhook provides real-time notifications to your system when a new wallet is successfully created, enabling seamless integration and automated updates.

Webhook Type

In the wallet (currently applicable only to customer wallets) creation workflow you should expect to receive the following webhooks:

Event	Description
`bvnk:ledger:wallet:create`	The wallet creation request has transitioned to a new state.

Data Types

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 wallet creation request. Possible values: `PROCESSING` `REJECTED` `COMPLETED`
`data.id`	Unique identifier of the wallet.
`data.walletName`	Name of the wallet.
`data.currencyCode`	Currency code of the wallet.
`data.accountReference`	Unique reference of the account that owns the wallet.
`data.customerReference`	Unique reference of the customer that owns the wallet. Optional.
`data.ledgers`	Information object about the ledger.
`data.ledgers[0].type`	Type of the ledger. Possible values: `FIAT` `CRYPTO`
`data.ledgers[0].code`	Code for the bank that issued the ledger. Provided only if `ledgers.type` = `FIAT`.
`data.ledgers[0].accountNumber`	Bank account number. Provided only if `ledgers.type` = `FIAT`.
`data.ledgers[0].accountNumberFormat`	Format of the account number. Provided only if `ledgers.type` = `FIAT`. Possible values: `IBAN` `SCAN` `SWIFT` `ABA` `BBAN` `CUBIX`
`data.ledgers[0].paymentReference`	Reference label to identify or describe the payment. If provided, all incoming deposits must include this text as a prefix in the `paymentReference` field. Without this prefix, we cannot automatically process your payment allocation, which may result in processing delays. If no `paymentReference` is specified, you may use any reference of your choice.

Webhook Example

{
    "event": "bvnk:ledger:wallet:create",
    "eventId": "0193da1c-a95f-7f7d-a524-f1a3654bec86",
    "timestamp": "2024-12-18T14:12:11.743368759Z",
    "data": {
        "id": "a:24121851098381:mohEmnT:1",
        "status": "COMPLETED",
        "ledgers": [
            {
                "code": "LHVBEE20",
                "type": "FIAT",
                "accountNumber": "EE047777000028534345",
                "accountNumberFormat": "IBAN"
            }
        ],
        "walletName": "Finance Wallet",
        "currencyCode": "EUR",
        "accountReference": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea",
        "customerReference": "f62a5da6-f727-4a6b-bb51-78003545b7ee"
    }
}

{
  "event": "bvnk:ledger:wallet:create",
  "eventId": "0197f9dd-5701-7557-8199-5eb5905c11a0",
  "timestamp": "2025-07-11T14:22:01.985393750Z",
  "data": {
    "id": "a:25071151684443:sUEpD0U:1",
    "status": "COMPLETED",
    "ledgers": [
      {
        "code": "BBVAESMMXXX",
        "type": "FIAT",
        "accountNumber": "ES9601828510912010000487",
        "accountNumberFormat": "SWIFT",
        "paymentReference": "REF-0SDGXS0"
      }
    ],
    "walletName": "John Doe SWIFT Wallet 10",
    "currencyCode": "USD",
    "accountReference": "768c21f7-6a6c-43f5-8cf8-9cb3793a664f",
    "customerReference": "f5c374c8-2134-4618-83c6-39d247d6fd50"
  }
}

Note thepaymentReference field in the example response for USD Wallets. It is designed to avoid an additional API call to the GET Wallet endpoint, and immediately present full payment details for sending funds to pooled USD SWIFT wallets.