Skip to main content
A webhook is an API endpoint made available to external applications that can be called to notify your application whenever a significant event occurs. This allows your app to react or respond immediately to these events. You can set a webhook URL per service on your Fapshi dashboard. When set, a POST request will be sent to this webhook URL whenever the status of a payment changes to:
  • SUCCESSFUL — when a payment attempt completes successfully
  • FAILED — when a payment attempt fails (usually on operator networks like MTN Mobile Money or Orange Money)
  • EXPIRED — when a payment link expires after 24 hours without successful payment
The payload of the webhook request will be the same as the response body returned when querying a payment status.

​
How Webhooks Work

Webhook Sequence Diagram
  1. Payment Initiated: Your external application initiates a payment by calling one of Fapshi’s payment endpoints (e.g., initiate-pay or direct-pay).
  2. Payment Processed: Fapshi Server processes the payment transaction. This includes handling the payment flow, communicating with payment operators, and updating the transaction status.
  3. Webhook Sent: When the payment status changes to SUCCESSFUL, FAILED, or EXPIRED, Fapshi Server automatically sends a POST request to your configured webhook URL with the updated transaction details.
  4. Webhook Received: Your external application receives the webhook notification and can process it accordingly (e.g., update your database, send notifications, trigger other workflows).
Your server should respond quickly to webhook requests to avoid timeouts, ideally with a 200 status code. Fapshi sends only one webhook request per event, regardless of whether your server responds or not.

​
Delivery and Retries

Webhooks are not retried automatically. If your server is down, times out, or returns an error, Fapshi will not send the notification again on its own.
If a webhook was not delivered: Because delivery is not guaranteed, do not rely on webhooks alone. Periodically check the status of transactions that are still CREATED or PENDING in your system. See the Reconciliation Checklist.

​
Webhook Security

You can authenticate the origin of a webhook request by setting a webhook secret on the Fapshi dashboard. When a secret is configured, every webhook request includes a header called x-wh-secret whose value is the secret you set on the dashboard. Comparing the value in this header to the secret you configured tells you whether the request came from Fapshi.
x-wh-secret is a static shared secret, not a signature. It is not an HMAC and is not computed from the request body; it is the exact value you set on the dashboard, sent unchanged with every webhook notification.
Recommended practice:
  • Reject any webhook whose x-wh-secret header is missing or does not match your secret.
  • Compare the values with a constant-time comparison function.
  • Only expose your webhook URL over HTTPS.
  • Before fulfilling an order, confirm the status with GET /payment-status/{transId}.
As a security measure, the dashboard does not let you view or determine whether a webhook secret has already been set for a service.

​
Webhook Payload Format

Response

200 - application/json

Acknowledgement of webhook receipt

​
transId
string

Transaction ID of the payment.

​
status
enum<string>

Transaction status

Available options:
CREATED,
PENDING,
SUCCESSFUL,
FAILED,
EXPIRED
​
medium
enum<string>

Payment method

Available options:
mobile money,
orange money,
fapshi
​
serviceName
string

Name of the service in use

​
transType
enum<string>

Type of transaction

Available options:
Collection,
Payout
​
amount
integer

Transaction amount

​
revenue
integer

Amount received when Fapshi fees (3% of amount) have been deducted

​
payerName
string

Client name

​
email
string<email>

Client email

​
redirectUrl
string<uri>

URL to redirect after payment

​
externalId
string

The transaction ID on your application

​
userId
string

ID of the client on your application

​
webhook
string<uri>

The webhook you defined for your service

​
reason
string

Typically appears when a payout via fapshi fails

​
financialTransId
string

Transaction ID with the payment operator

​
dateInitiated
string<date>

Date when the payment was initiated

​
dateConfirmed
string<date>

Date when the payment was made