Link.Transaction.StatusUpdateV2

This section describes the structure of the event payload Balad sends to your registered webhook URL when a transaction status changes. This is the Version 2 (v2) payload structure.

📦 Payload Structure

The webhook payload is a standardized event envelope that contains metadata about the event and the transaction status information nested within the data object.

Field	Type	Description
`id`	`string`	A unique identifier for this specific webhook event.
`eventType`	`string`	The type of event. For transaction status updates, this is typically `994019`.
`timestamp`	`string`	The date and time the event was generated (e.g., `25-Nov-2025 08:52:02 AM`).
`version`	`string`	The version of the webhook payload structure. Currently `2`.
`data`	`object`	Contains the core transaction status details.

`data` Object Fields

Field	Type	Description
`referenceNumber`	`string`	Your unique reference number for the transaction.
`transactionStatusCode`	`integer`	The numeric code representing the status. See Get transaction status V2 for a full list.
`transactionStatusDescription`	`string`	The human-readable description of the status.
`reason`	`string`	Optional field providing a brief technical or internal reason for the status change.
`failureDetails`	`object` / `null`	Provides details on the cause of failure/rejection (only present if `transactionStatusCode` indicates a failure).

`failureDetails` Object Fields

This object is identical to the one returned by the Get Transaction Status v2 endpoint. Get transaction status V2

Field	Type	Description
`category`	`string`	The high-level parent category of the rejection (e.g., `COMPLIANCE_RESTRICTION`).
`code`	`string`	The specific Balad rejection code (e.g., `CMP_001`).
`message`	`string`	The user-friendly explanation/message.
`additionalInfo`	`string`	Any supplemental information related to the failure.

➡️ Example Event Payload

This example shows the payload for a Bank Compliance Rejected status, using the camelCase convention, and including the failureDetails.

{
  "id": "180377",
  "eventType": "994019",
  "timestamp": "25-Nov-2025 08:52:02 AM",
  "version": "2",
  "data": {
    "referenceNumber": "Ref-1764060698635",
    "transactionStatusCode": 17,
    "transactionStatusDescription": "Bank Compliance Rejected",
    "reason": "Bank-failure due to sandbox suffixes rules",
    "failureDetails": {
      "category": "COMPLIANCE_RESTRICTION",
      "code": "CMP_001",
      "message": "Rejected due to AML / sanctions screening",
      "additionalInfo": ""
    }
  }
}

Link.Transaction.StatusUpdateV2

📦 Payload Structure#

data Object Fields#

failureDetails Object Fields#

➡️ Example Event Payload#

📦 Payload Structure

`data` Object Fields

`failureDetails` Object Fields

➡️ Example Event Payload