📑 Webhooks

A webhook is an HTTP POST that BillStack sends to your server the moment something happens - most importantly, when a customer pays into one of your virtual accounts. Instead of polling the API, you register a URL once and BillStack pushes events to it as they occur.

Set your webhook URL

Add your endpoint URL in the dashboard under Developer → Webhooks. It must be a public https URL that accepts POST requests with a JSON body.

The payment event

When funds arrive in a virtual account, BillStack sends a PAYMENT_NOTIFICATION event:

{
  "event": "PAYMENT_NOTIFICATION",
  "data": {
    "type": "RESERVED_ACCOUNT_TRANSACTION",
    "reference": "virtual_account_reference",
    "merchant_reference": "virtual_account_reference",
    "wiaxy_ref": "inter_bank_reference",
    "transaction_ref": "inter_bank_reference",
    "amount": "payment_amount",
    "created_at": "receiving_date",
    "account": {
      "account_number": "customer_account_number",
      "account_name": "customer_account_name",
      "bank_name": "customer_bank_name",
      "created_at": "account_creation_date"
    },
    "payer": {
      "account_number": "payer_acct_num",
      "first_name": "payer_first_name",
      "last_name": "payer_last_name",
      "createdAt": "payment_date"
    }
  }
}

Fields

Field	Description
`event`	The event type. Currently `PAYMENT_NOTIFICATION`.
`data.type`	The kind of transaction. `RESERVED_ACCOUNT_TRANSACTION` for a virtual-account payment.
`data.reference` / `data.merchant_reference`	The reference of the virtual account that was paid into.
`data.wiaxy_ref` / `data.transaction_ref`	The interbank reference for this transaction.
`data.amount`	The amount received.
`data.created_at`	When the payment was received.
`data.account`	The virtual account that received the funds (number, name, bank).
`data.payer`	The sender’s account number and name.

Responding to a webhook

Reply with an HTTP 200 as soon as you have received the event, and return this JSON body to acknowledge it:

{
  "status": true,
  "message": "successful"
}

Any non-200 response is treated as a failed delivery, and BillStack retries it.

Acknowledge with 200 first, then do your processing (fulfilling the order, updating your records) afterwards. Keeping the handler fast avoids timeouts that look like failed deliveries.

Each event you accept with a 200 is recorded as delivered. Verifying that an event genuinely came from BillStack is covered on the next page, Webhook Security.

Getting Started

Webhooks

Reserved Accounts

Transactions

Set your webhook URL

The payment event

Fields

Responding to a webhook

​Set your webhook URL

​The payment event

​Fields

​Responding to a webhook

Set your webhook URL

The payment event

Fields

Responding to a webhook