Home
Release Notes
Home
Release Notes
Linkedin
  1. Webhooks
  • Balad™ Gateway Documentation 📖
  • Get Started
  • Authorization
  • Responses
  • Go Live!
  • FAQs
  • APIs
    • Authentication
      • Token
    • Core
      • Exchange rate
        • Exchange Rates
      • Balance
        • Get Current Balance
      • Secrets
        • Generate Secret
        • Delete Secret
        • Get Secrets
    • Link
      • Sandbox Testing Guide
      • Error Codes
      • Transaction Lifecycle V2
      • Lookups
        • Purposes List
        • Sources List
        • Banks List
        • Relations
      • Transactions
        • Create transaction
        • Update transaction
        • Cancel transaction
        • Get transaction status V2
        • Transactions List
        • Export Transactions List
        • Validate Account
        • Request Sender Document Upload URL
        • Check Sender Document
      • Reconciliation
        • Reconciliation
      • Quotations
        • Create Quotation
  • Webhooks
    • Link.Transaction.StatusUpdateV2
    • Link.Transaction.BankReferenceAvailable
  1. Webhooks

Link.Transaction.BankReferenceAvailable

This section describes the structure of the event payload Balad sends to your registered webhook URL when the bank reference number of a transaction becomes available or changes. This is the Version 2 (v2) payload structure. All keys in the payload use snake_case by default.

📦 Payload Structure#

The webhook payload is a standardized event envelope that contains metadata about the event and the bank reference details nested within the data object.
FieldTypeDescription
idstringA unique identifier for this specific webhook event.
event_typestringThe unique identifier of the event that triggered this webhook (e.g., 648438).
event_type_descriptionstringThe name of the event type. For this event, this is Link.Transaction.BankReferenceAvailable.
timestampstringThe date and time the event was generated (e.g., 16-Nov-2026 02:18:27 PM).
versionstringThe version of the webhook payload structure. Currently 2.
dataobjectContains the bank reference details.

data Object Fields#

FieldTypeDescription
partner_reference_numberstringYour unique reference number for the transaction (the remitter_reference_no sent in Create transaction).
bank_reference_nostringThe reference number assigned to the transaction by the bank.

➡️ Example Event Payload#

{
  "id": "227870",
  "event_type": "648438",
  "event_type_description": "Link.Transaction.BankReferenceAvailable",
  "timestamp": "16-Nov-2026 02:18:27 PM",
  "version": "2",
  "data": {
    "partner_reference_number": "Ref-1794838589567",
    "bank_reference_no": "32434324324543"
  }
}

🔐 Signature and Retries#

Signature: every request has an X-HMAC-SIGNATURE header. Its value is the HMAC-SHA256 of the raw request body, using the secret you set for your webhook endpoint as the key, as a lowercase hex string. Compute the same value on your side and compare it before you trust the request.
Retries: if your endpoint does not return a 2xx status (or cannot be reached), Balad retries the delivery every 1 hour, up to 5 attempts in total.
Previous
Link.Transaction.StatusUpdateV2
Built with