Webhooks

WaafiPay offers webhook notifications to keep you informed about transaction status updates. A webhook is an HTTP callback that automatically sends real-time data to a pre-configured URL when specific events occur, such as the completion or failure of a transaction. This enables your system to immediately receive and process updates without the need for constant polling. Please note that webhook notifications are currently supported only for transactions processed via the Hosted Payment Page (HPP), and failed webhook deliveries do not trigger automatic retry attempts.

Merchants can register their webhook endpoints via our API, receiving real-time updates about transaction outcomes, including both successful completions and failures. To ensure robust integration, it is recommended to implement proper logging and error-handling mechanisms for webhook events on your end. This is especially important to prevent missing crucial information due to issues like failed customer redirection (such as HPP callbacks).

If you need any help with integration or have further questions, feel free to reach out. We're here to help!

1. Register a Webhook

You can only register one webhook URL to receive payment notifications. The provided URL should be publicly accessible.

In all API requests, you must include the HPP credentials: merchantUid, storeId, hppKey.

Request:

POST /asm
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_REGISTER",
    "serviceParams": {
        "merchantUid": {{MERCHANT_UID}},
        "storeId": {{STORE_ID}},
        "hppKey": {{HPP_KEY}},
        "url": "https://api.example.com/webhook",
        "description": "a description"
    }
}

Request Parameters

Parameter	Data Type	Presence	Description
`schemaVersion`	String	Constant	API schema version (e.g., "1.0").
`requestId`	UUID String	Required	Unique request identifier (e.g., UUID).
`timestamp`	String	Required	Date and time of the request.
`channelName`	String	Constant	The channel through which the request was made.
`serviceName`	String	Constant	The name of the service being called (e.g., WEBHOOK_REGISTER).
`merchantUid`	String	Required	Unique merchant identifier.
`storeId`	String	Required	API store/user identifier for the merchant.
`hppKey`	String	Required	API key for request authentication.
`partnerUid`	String	Optional	WAAFI Merchant Number (PartnerUID).
`description`	String	Optional	Description of your webhook usage.
`url`	String	Required	URL for webhook to be sent to. Only one webhook endpoint is allowed per merchant.

Response:

{
    "schemaVersion": "1.0",
    "timestamp": "2024-02-08 04:38:42.938",
    "responseId": "{{$guid}}",
    "responseCode": "2001",
    "errorCode": "0",
    "responseMsg": "Webhook created successfully",
}

2. Get All Webhooks

Retrieve a list of all existing webhooks.

POST Request

POST /asm
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_LIST",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": {{STORE_ID}},
        "hppKey": "{{HPP_KEY}}",
    }
}

Response

{
    "params": {
        "data": [
            {
                "id": "25",
                "url": "https://app.sample.com/webhook",
                "description": "testing",
                "merchantId": "10165",
                "partnerUid": "400394",
                "merchantName": "WaafiPay Store"
            }
        ]
    }
}

3. Update Webhook

You can update the url and description properties of an existing webhook.

POST Request

POST /asm
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_UPDATE",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": {{STORE_ID}},
        "hppKey": "{{HPP_KEY}}",
        "url": "https://api.sample.so/webhook/v2",
        "webhookId": 10,
        "description": "another description"
    }
}

4. Delete Webhook

Remove an existing webhook.

POST Request

POST /asm
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_DELETE",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": {{STORE_ID}},
        "hppKey": "{{HPP_KEY}}",
        "webhookId": 10,
    }
}

Receiving a Webhook on Your Server

Once registered, your webhook URL will receive transaction notifications in the following format:

Webhook Sample Payload

{
    "customerNumber": "252613282000",
    "customerName": "Mohamed Abdullahi Abdi",
    "partnerUID": "${MERCHANT_UID}",
    "transferInfo": {
        "amount": "10",
        "charges": "0",
        "transferId": "176329573",
        "transferCode": "1017635883",
        "transactionDate": "08/02/23 19:15:38",
        "transferStatus": "3",
        "currencySymbol": "$",
        "referenceId": "1001",
        "currencyCode": "840",
        "currencyName": "UNITED STATES-US Dollar",
        "paymentChannel": "MOBILEAPP",
        "description": "Invoice No: 1001",
        "tokenReferenceId": "223"
    }
}

Please ensure your server is properly configured to handle these notifications to keep your system up-to-date with transaction statuses.

On this page