{
"version": "V1.6.0",
"event_name": "VIRTUAL",
"event_type": "virtual.account.create",
"event_id": "550e8400-e29b-41d4-a716-446655440101",
"source_id": "550e8400-e29b-41d4-a716-446655440001",
"data": {
"account_id": "b1b89684-c2c4-4d54-b8a8-3572727fd120",
"application_id": "550e8400-e29b-41d4-a716-446655440001",
"country": "BH",
"currency": "EUR",
"direct_id": "0",
"public_version": 1,
"results": [
{
"payment_method": "SWIFT",
"status": "SUBMITTED",
"virtual_accounts": [],
"error": null
}
],
"status": "SUBMITTED"
}
}Account & Virtual Account
Virtual Account Application Webhooks
Receive application acceptance, update, and closure events safely.
WEBHOOK
virtualAccountCreateUpdate
{
"version": "V1.6.0",
"event_name": "VIRTUAL",
"event_type": "virtual.account.create",
"event_id": "550e8400-e29b-41d4-a716-446655440101",
"source_id": "550e8400-e29b-41d4-a716-446655440001",
"data": {
"account_id": "b1b89684-c2c4-4d54-b8a8-3572727fd120",
"application_id": "550e8400-e29b-41d4-a716-446655440001",
"country": "BH",
"currency": "EUR",
"direct_id": "0",
"public_version": 1,
"results": [
{
"payment_method": "SWIFT",
"status": "SUBMITTED",
"virtual_accounts": [],
"error": null
}
],
"status": "SUBMITTED"
}
}Virtual Account application webhooks are available for subscriptions using version
The Create response and
V1.5.1, V1.5.2, or V1.6.0.
Each event represents the whole application. source_id equals data.application_id, and data contains the latest application details after the event. Events are not sent separately for each receiving method or bank-detail record.
Use data.account_id to identify the account that owns the application. When this is a connected account, data.direct_id identifies its main account; when it is the main account, data.direct_id is "0".
virtual.account.create means the application was accepted for processing. It does not mean approval is complete or bank details are ready. Use only bank-detail records whose status is ACTIVE.When events are sent
| Event type | When it is sent | What to do |
|---|---|---|
virtual.account.create | A new application is accepted. Its public_version starts at 1. | Store the application and continue tracking any SUBMITTED result. |
virtual.account.update | Returned application data changes and the application is not fully closed. | Apply the event only when public_version is higher than the version you stored, then process every result. |
virtual.account.closed | All issued Virtual Accounts are closed and no result remains in progress. | Apply the CLOSED application and stop using all related bank details. |
virtual.account.create webhook can arrive in either order. Do not make one wait for the other.
An update can report a skipped or failed method, newly issued bank details, partial completion, final completion, or the closure of an individual bank-detail record. If two methods complete in one change, one final update is sent. If they complete at different times, a partial update is followed by a final update.
When an issued bank-detail record closes, use its status immediately. close_reason can still be empty for a closed record.
When events are not sent
No application webhook is sent when:- Create returns a synchronous
4xx. - Every evaluated receiving method is rejected and no application is created.
- An identical request is replayed with the same
x-idempotency-key. - Processing continues but the returned application data has not changed.
Process events safely
- Verify
x-wk-signaturefrom the raw request body andx-wk-timestamp. See Signature verification. - Deduplicate deliveries by
event_id. Retries of the same event reuse this value. - Route the event to the account identified by
data.account_id, usingdata.direct_idto identify its main account when applicable. - Locate the application by
data.application_id. - Apply the event only when
data.public_versionis higher than the version already stored for that application. - Process every entry in
data.results[]and identify it bypayment_method. - Retrieve the latest application after a delivery gap or suspected out-of-order event.
public_version as newer, even if the application previously reached FAILED.
See Integrate Virtual Accounts with the API for status meanings, error actions, and bank-detail availability rules.Body
application/json
A unique identifier for this event.
Top-level event category.
Available options:
VIRTUAL The specific event type that occurred.
Available options:
virtual.account.create, virtual.account.update, virtual.account.closed Virtual Account application ID.
API version number.
Example:
"V1.6.0"
Latest application data after this event. Use application_id and public_version to apply events in order.
Show child attributes
Show child attributes
Response
200
Return 200 to acknowledge receipt.