Webhooks

With webhooks, the resource server (54Pay) sends updates to your server whenever the status of your request changes. A change in request status is sent via webhooks. You will typically listen for these changes on a POST endpoint, which acts as your webhook URL.

Webhook Configuration

A webhook URL is simply a POST endpoint designed to receive updates from the resource server. When an event occurs, your webhook URL must parse the incoming JSON request and immediately acknowledge receipt by returning a 200 OK status in the HTTP header.

How to Set Up Your Webhook URL

1. Sign in to your 54Pay Dashboard.
2. Locate and click on the Settings menu in the left-hand sidebar.
3. Choose API and Keys from the list of options.
4. Select the API Configuration tab.
5. Input your webhook URLs and click Save Changes to finalize.

Webhook Verification

Because your webhook URL is publicly available, you must verify that incoming events genuinely originate from 54Pay and not a malicious actor. There are three methods to ensure event authenticity:

• Signature Validation
• TSQ Verification
• IP Whitelisting

Signature Validation

Events sent from 54Pay include a webhook hash header. The value of this header (x-54pay-signature) is an HMAC SHA-512 signature of the event payload, signed using your secret key. You must verify this header signature before processing the event payload.

Node.js example:

const crypto = require('crypto');
const secret = process.env.SECRET_KEY;

// Using Express
app.post("/my/webhook/url", function(req, res) {
	 // Validate the event
	 const hash = crypto.createHmac('sha512', secret)
											.update(JSON.stringify(req.body))
											.digest('hex');
                      
	 if (hash === req.headers['x-54pay-signature']) {
			 // Retrieve the request's body
			 const event = req.body;
       
			 // Process the webhook
	 }
   
	 // Acknowledge receipt
	 res.sendStatus(200);
});

(Note: Code examples for PHP, Java, and C# can follow the same cryptographic logic using their respective standard libraries.)

Transaction Status Query (TSQ)

Performing a Transaction Status Query (TSQ) allows you to independently verify the status and data provided in the webhook payload. Cross-referencing these details against the 54Pay server ensures the event's authenticity before you finalize your processing.

IP Whitelisting

With this method, you explicitly allow only certain IP addresses to access your webhook URL while blocking all others. 54Pay will exclusively send webhooks from a dedicated IP address (shared privately upon request). You should whitelist this IP address on your server and treat requests from any other IP addresses as counterfeit.

Sample Payloads

Collections

{
	"transaction_reference": "PG-C-177460878255880",
	"transaction_status": "Funds Received",
	"transaction_fee": 5,
	"amount_received": 150,
	"initiated_date": "2026-03-27 11:53:02",
	"current_status_date": "2026-03-27 11:53:05",
	"received_from": {},
	"merchant_reference": "QATXN25235350",
	"status": "COMPLETED",
	"channel": "MOBILE_MONEY",
	"currency_code": "RWF"
}

Payouts

{
	"data": {
		"transactionStatus": "COMPLETED",
		"merchantReference": "TXN3232344100003079",
		"transactionReference": "PG-P-1774609410715V1",
		"amount": 100,
		"feeAmount": 5,
		"valueAmount": 100,
		"statusReason": "SUCCESS",
		"channel": "BANK_TRANSFER"
	}
}

Go-Live Checklist

Now that you’ve successfully created your webhook URL, use this checklist to ensure a reliable and delightful integration experience:

• Add the webhook URL to your 54Pay dashboard.
• Verify public availability: Ensure your webhook URL is publicly accessible (localhost URLs cannot receive events).
• Perform a test run: Test your webhook to ensure you are successfully parsing the JSON body and returning a 200 OK HTTP response.
• Handle long-running tasks asynchronously: If your webhook function triggers long-running tasks, immediately acknowledge receiving the webhook (return 200 OK) before proceeding with those tasks.
• If 54Pay does not receive a 200 OK HTTP response, the attempt is flagged as failed.
• Store webhook payloads received from 54Pay for audit trail.