9th Swift Documentation
We help African businesses get paid by anyone, anywhere in the world—while giving them the tools to collect payments, access loans, and manage daily operations through a complete business banking solution.
9thSwift Webhook Documentation
Introduction
The webhook service allows real-time communication of transaction notifications between your system and 9thSwift. You can receive transaction details promptly, enabling you to process them efficiently within your application.
Quick Start
- Add your webhook URL on the 9thSwift dashboard.
- Ensure your webhook URL is publicly available (localhost URLs cannot receive events).
- Implement signature validation using the ApiKey header.
- Test your webhook to ensure you’re getting the JSON body and returning a
200 OKHTTP response.
Webhook URL
You can add your webhook URL from your dashboard. Example: https://api.yourdomain.com/webhook
Endpoint: POST your-web-hook-url
Signature Validation
Events sent from 9thSwift carry an ApiKey header. The value of this header is your API secret key. Verifying the header signature should be done before processing the event.
const apiKey = process.env.SECRET_KEY;
app.post("/my/webhook/url", function(req, res) {
//validate event
const signature = req.header('ApiKey')!.replace('ApiKey ', '');
if (!signature || (signature !== apiKey)) {
throw new Error('Webhook notification not from 9th Swift');
}
// Retrieve the request's body
const event = req.body;
// Send acknowledge
res.status(200).send('ok');
// Do something with event
});Supported Events
| Event Type | Description |
|---|---|
payment.success | Successful Transaction for all channels |
payment.failed | Failed Transaction for channels |
payment.pending | Pending Transaction for all channels |
transfer.success | Successful Payout Transfer |
transfer.failed | Failed Payout Transfer |
refund.processed | Processing Refund |
Payload Format
Webhook payloads are JSON objects containing information about the event. Below is an example payload for a payment.success event:
{
"id": "67ec7641416a8374c865a167",
"type": "payment.success",
"created": "2025-09-03T10:40:18.742+00:00",
"data": {
"reference": "MFNRCBW0-SW-AFHJTTSA-M",
"status": "success",
"amount": 1025,
"settledAmount": 1000,
"chargedFee": 25,
"currency": "NGN",
"paymentChannel": "card",
"processorResponse": "Card 3DS verification successfully",
"ip_address": "1.345.907.234",
"paidAt": "2025-08-27 14:06:02",
"customer": {
"fullName": "John Doe",
"email": "[email protected]",
"phoneNumber": "909665234187"
},
"paymentDetails": {
"method": "card",
"first6Digits": "123456",
"last4Digits": "1992",
"cardType": "master",
"expiry": "04/26"
},
"environment": "live",
"log": {
"time_spent": null,
"attempts": null,
"authentication": null,
"errors": 3,
"success": true,
"channel": "card",
"history": [
{
"id": 8422,
"type": "TRANSACTION RECORDED",
"message": "success",
"time": null,
"reference": "METYZHJT-SW-LK12MUJCV7",
"channel": "S2S",
"ip_address": "102.91.102.183",
"device": "axios/1.11.0"
}
]
}
}
}Handling Webhooks
- Receive the webhook payload via POST request.
- Validate the
ApiKeyheader against your secret key. - Parse the JSON payload to extract event details.
- Process the event according to your business logic.
- Respond with a
200 OKstatus code to acknowledge receipt.
Avoid long-running tasks
If your webhook function has long-running tasks, you should first acknowledge receiving the webhook by returning a 200 OK before proceeding with the long-running tasks.
Important Notes
- If we don’t get a
200 OKHTTP response from your webhooks, we flag it as a failed attempt. - If we are unable to deliver a webhook to you, there is an API to recall failed webhook notifications (contact support for details).
Retry & Recall
Failed deliveries (non-2xx responses) are flagged for manual recall via our API. Contact support for the recall endpoint details.