> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Webhooks receive messages based on events triggered in the system, they are an important part of your payment integration. Webhooks are responsible for notifying you about events that happen on your accounts, such as pending, successful, or failed transactions.
Webhooks are used to configure and receive notifications when a specific event occurs. When one of these events is triggered, we send a **POST** payload in JSON which contains the details about the event, to the webhook's configured URL. Setting up a webhook allows us to notify you when these payments are completed. Payaza sends webhooks for:
* Payouts
* Collections
### When to use webhooks
Webhooks are event-based and enable real-time updates of third-party systems as they are triggered and sent out immediately when specific events related to the transaction happen. They're useful for methods and events that occur outside your application's control, such as:
* Getting paid via mobile money or USSD
* Pending payment transactions to successful
These are all non-simultaneous actions i.e. they are not controlled by your application, so you won't know when they are completed unless we notify you or you check later. Webhooks can be set up by users using the **Payaza** Dashboard to configure separate URLs for **Live** mode and **Test** mode.
Webhook notifications include an authentication header with your public key encoded in **base64** format. This can be used to validate that a webhook notification was sent from us.
**Idempotency:** Process transactions based on their unique transaction\_reference to avoid duplicate actions.
### Validating Webhook Payloads with HMAC
Our webhook notifications include a header called **x-payaza-signature** which is an **HMAC SHA512** signature generated from the event payload using your secret key.
To ensure the integrity and authenticity of webhook events:
* Always validate the **x-payaza-signature** before processing any event.
* Compute an **HMAC SHA512** hash using the received payload and your secret key. The secret key doesn't need to be base64 encoded
* Compare the generated hash with the **x-payaza-signature** in the request header.
* Ensure that the event is processed only if the computed hash matches the received signature
### HMAC Sample
```json theme={null}
const crypto = require('crypto');
// Define the request body (ensure it's exactly the same as in cURL)
const requestBody = {{webhookNotificationBody}};
// Secret key used for hashing
const secretKey = ""{{secretKey}}";
// Expected signature from webhook header
const predefinedSignature = "{{predefinedKey}}";
// Function to generate HMAC-SHA512 signature
function hmacSHA512(data, secretKey) {
return crypto.createHmac('sha512', secretKey) // Use SHA512
.update(data, 'utf8') // Encode as UTF-8
.digest('base64'); // Encode output as Base64
}
// Generate Computed signature
const computedSignature = hmacSHA512(requestBody, secretKey);
// Compare computed signature with predefined signature
if (computedSignature === predefinedSignature) {
console.log("✅ SIGNATURE MATCHED SUCCESSFULLY!");
} else {
console.error("❌ Signature Mismatch. Please check your credentials.");
}
```
### How To Set Up Your Webhook URL
* Log in to your **Payaza** dashboard
* Click on the **Settings** option which is located on the left side-bar of the dashboard
* Click on the **Developers** option from the dropdown menu.
* Navigate to add your respective webhook URL to each transaction type.
* Select the **Update Webhooks** button to update your webhook URLs
## Payaza Webhook Notification Samples
### Transfer
```json Successful transfer theme={null}
{
"transaction_reference": "PTSA1220246261518348000",
"transaction_type": "DEBIT",
"transaction_status": "NIP_SUCCESS",
"transaction_fee": 10.0,
"amount_received": 20.0,
"sent_to": {
"account_name": "John Doe",
"account_number": "1234567890",
"bank_name": "EASTWE BANK"
},
"initiated_date": "2024-06-26 16:44:08.718",
"current_status_date": "2024-06-26 16:44:08.718",
"is_reversed": false,
"response_message": "Approved or Completely Successful",
"response_code": "00",
"currency": "NGN",
"country": "NGA",
"session_id": "999999213419011273456123134124"
}
```
```json Failed transfer theme={null}
{
"narration": "PTSA1220246261518348001",
"transaction_reference": "PTSA1220246261518348001",
"transaction_type": "DEBIT",
"transaction_status": "NIP_FAILURE",
"transaction_fee": 100,
"amount_received": 50000,
"sent_to": {
"account_name": "John Doe",
"account_number": "1234567890",
"bank_name": "EASTWE BANK"
},
"initiated_date": "2024-06-26 16:44:08.718",
"current_status_date": "2024-06-26 16:44:08.718",
"is_reversed": true,
"response_message": "Invalid Account",
"response_code": "07",
"currency": "NGN",
"country": "NGA"
}
```
## Collections
This webhook notifies your server when a collection event occurs (funds received, failed, status updates). Use it to update order state, reconcile payments, trigger downstream flows, or notify customers.
```json Collection webhook theme={null}
{
"transaction_reference": "I3427072178",
"transaction_status": "Funds Received",
"virtual_account_number": "",
"transaction_fee": 50,
"amount_received": 2500,
"initiated_date": "2025-12-04 09:36:07",
"current_status_date": "2025-12-04 09:36:19",
"received_from": {
"account_name": "John Doe",
"account_number": "22901xxxxxxxx",
"bank_name": "N/A"
},
"merchant_reference": "17649602",
"status": "Completed",
"session_id": "1764837367925",
"channel": "BENIN_COLLECTIONS",
"branch": true,
"currency_code": "XOF",
"business_fk": 1010,
"business_branch_fk": 3239,
"customer": {
"email_address": "ceojiaku@gmail.com",
"first_name": "Test",
"last_name": "Reference",
"mobile_number": "01232425262"
},
"request_amount": 25000,
"amount_validation": "EXACT"
}
```
### Field Reference
| Name | Format | Description |
| :----------------------- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transaction_reference` | `string` | Unique reference assigned to the transaction |
| `transaction_status` | `string` | Status for the transaction.
Values: **Funds Received**, **Transaction Failed**
This describes the event that triggered the webhook. |
| `virtual_account_number` | `string` | The virtual account number used to collect funds (present for Virtual Account collection flows). |
| `transaction_fee` | `double` | Fee charged on the transaction |
| `amount_received` | `double` | Amount received on this transaction |
| `initiated_date` | `string (datetime)` | When the payer initiated the transaction. |
| `current_status_date` | `string (datetime)` | Timestamp when the current webhook status was recorded. |
| `received_from` | `array` | Contains the Payer’s details |
| └── `account_name` | `string` | Payer account name |
| └── `account_number` | `string` | Payer account number (may be null for some channels). |
| └── `bank_name` | `string` | Payer bank name (may be null for some channels). |
| `merchant_reference` | `string` | Your merchant reference (returns for VA & Checkout collection). |
| `status` | `string` | Status of operation.
Values: **Completed**, **Failed** |
| `session_id` | `string` | Session identifier for the payment flow |
| `channel` | `string` | Collection channel.
`BENIN_COLLECTIONS`, `EFT_COLLECTIONS`, `GH_MOBILEMONEY`, `CAMEROUN_COLLECTIONS`, `CIV_COLLECTIONS`, `KENYA_COLLECTIONS`, `UGANDA_COLLECTIONS`, `TANZANIA_COLLECTIONS`, `VirtualAccount`, `Card`, `Apple Pay`, `Google Pay` |
| `branch` | `boolean` | Whether a branch-collected payment is involved (true/false). |
| `currency_code` | `string` | ISO-4217 currency code.
Examples: XOF, GHS, KES, UGX, TZS, NGN, ZAR, XAF, USDT, USDC. |
| `business_fk` | `integer` | Internal business/merchant foreign key |
| `business_branch_fk` | `integer` | Returns when branch value is true |
| `customer` | `array` | The customer’s information |
| └── `email_address` | `string` | Customer’s email address |
| └── `first_name` | `string` | Customer’s first name |
| └── `last_name` | `string` | Customer’s last name |
| └── `mobile_number` | `string` | Customer’s mobile number |
| `request_amount` | `double` | The amount passed in the payload request |
| `amount_validation` | `string` | Validation of amount paid.
Values: **EXACT**, **UNDERPAYMENT**, **OVERPAYMENT** |