Billswave Webhook API v1.0

Webhook Integration Guide

Webhooks allow your application to receive real-time HTTP POST notifications whenever a customer pays into a static or dynamic virtual account generated on Billswave.

Overview & Workflow

When funds are successfully transferred into any of your merchant accounts, Billswave immediately processes the credit, updates your wallet balance, and dispatches a JSON payload via an HTTP POST request to your configured Webhook URL.

HTTP Method

POST

Header

Content-Type: application/json

User-Agent: Billswave-Webhook-Engine/1.0

Timeout Expectation

< 10 Seconds

Sample JSON Payload

JSON

{
  "account_number": "9012345678",
  "bank_name": "Moniepoint Microfinance Bank",
  "account_name": "Billswave / John Doe",
  "amount": 5000.00,
  "session_id": "000013240928181200000000000123"
}

Payload Fields

account_number string

The virtual account number that received the bank transfer credit.

bank_name string

The partner bank where the account is hosted.

account_name string

The assigned name on the virtual account.

amount float

Total gross amount deposited in NGN.

session_id string

Unique bank session reference. Crucial for duplicate checks.

Sample Integration Implementation

Here is how you can process and store incoming Billswave webhooks securely in PHP:

webhook_receiver.php

<?php
// Always respond with 200 HTTP status code immediately
http_response_code(200);

// Capture raw body payload
$input = file_get_contents("php://input");
$data = json_decode($input, true);

if (!$data) {
    exit("Invalid Payload");
}

$account_number =$data['account_number'] ?? '';
$bank_name      =$data['bank_name'] ?? '';
$account_name    =$data['account_name'] ?? '';
$amount          = (float)($data['amount'] ?? 0);
$session_id      =$data['session_id'] ?? '';

// 1. Idempotency Check: Query your database using $session_id to prevent double-crediting
// 2. Locate customer associated with $account_number
// 3. Credit customer balance & record transaction
// 4. Return success

exit("Webhook processed successfully");
?>

Integration Best Practices

1. Implement Idempotency

Always store and verify the incoming session_id against your database before crediting user balances to prevent processing duplicate requests.

2. Rapid HTTP 200 Response

Return an HTTP status code 200 OK immediately upon parsing the payload. Avoid performing long-running background tasks synchronously during the webhook request.

3. Secure Endpoint

Ensure your webhook receiver URL is served over a valid HTTPS protocol to encrypt transaction payload delivery.