Webhooks

SplashPay uses webhooks to notify your application whenever a payment reaches a final state. Instead of continuously polling the Payment Status endpoint, configure a webhook endpoint to receive instant updates.

Real-time Notifications

SplashPay automatically sends an HTTP POST request to your webhook URL whenever a payment status changes.

Configure Your Webhook URL

You can configure your webhook URL from the SplashPay Merchant Dashboard or via the Merchant API. Example:

https://merchant.example.com/webhooks/splashpay

Your endpoint must:

Support HTTPS
Accept HTTP POST requests
Return HTTP 200 OK after successful processing
Be publicly accessible

Webhook Events

SplashPay currently sends the following events.

Event	Description
`payment.success`	Payment completed successfully.
`payment.failed`	Payment failed.
`payment.cancelled`	Payment was cancelled by the customer or provider.
`payment.expired`	Payment expired before completion.
`payment.user_cancelled`	Payment was cancelled by the user.
`payment.in_progress`	Payment is in progress.
`payment.pending`	Payment is pending.
`payment.rejected`	Payment was rejected.

Sample Webhook

SplashPay sends webhook notifications using the following JSON structure.

{
  "event": "payment.success",
  "created_at": "2026-06-24T09:59:24.430757Z",
  "data": {
    "reference": "INV-xcxoddfudjhg",
    "amount": "1000.00",
    "fee": "15.00",
    "net_amount": "985.00",
    "currency": "TZS",
    "status": "success",
    "customer_name": "John Doe",
    "customer_email": "john.doe@example.com",
    "customer_phone": "255744123456",
    "payment_method": "mobile_money",
    "provider": "selcom",
    "channel": "TIGOPESATZ",
    "provider_reference": "1769142083",
    "metadata": null
  }
}

Webhook Payload

Field	Type	Description
`event`	string	Event name.
`created_at`	datetime	Time the webhook was generated.
`data.reference`	string	Merchant payment reference.
`data.amount`	decimal	Payment amount.
`data.fee`	decimal	Processing fee charged.
`data.net_amount`	decimal	Amount settled after fees.
`data.currency`	string	Transaction currency.
`data.status`	string	Payment status.
`data.customer_name`	string	Customer full name.
`data.customer_email`	string	Customer email.
`data.customer_phone`	string	Customer phone number.
`data.payment_method`	string	Payment method used.
`data.provider`	string	Payment provider.
`data.channel`	string	Provider channel or network.
`data.provider_reference`	string	Provider transaction reference.
`data.metadata`	object/null	Merchant-defined metadata.

Verify Webhook Signature

Every webhook request includes a signature that allows you to verify the payload originated from SplashPay.

Header	Description
`X-SPLASHPAY-SIGNATURE`	HMAC SHA-256 signature of the payload
`X-SPLASHPAY-TIMESTAMP`	Unix timestamp used to generate the signature

Compute the HMAC using your Webhook Secret.

HMAC_SHA256(
    timestamp + "." + request_body,
    WEBHOOK_SECRET
)

If the computed signature matches the X-SPLASHPAY-SIGNATURE header, the request is authentic.

Example Verification (PHP)

$timestamp = $_SERVER['HTTP_X_SPLASHPAY_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_SPLASHPAY_SIGNATURE'];

$payload = file_get_contents('php://input');

$expected = hash_hmac(
    'sha256',
    $timestamp.'.'.$payload,
    env('SPLASHPAY_WEBHOOK_SECRET')
);

if (!hash_equals($expected, $signature)) {
    abort(401, 'Invalid Signature');
}

Example Verification (Node.js)

import crypto from "crypto";

const payload = JSON.stringify(req.body);

const expected = crypto
    .createHmac(
        "sha256",
        process.env.SPLASHPAY_WEBHOOK_SECRET
    )
    .update(
        `${req.headers["x-splashpay-timestamp"]}.${payload}`
    )
    .digest("hex");

if (
    expected !==
    req.headers["x-splashpay-signature"]
) {
    return res.status(401).send("Invalid signature");
}

Return HTTP 200

After successfully processing the webhook, return:

HTTP/1.1 200 OK

Example

{
    "success": true
}

Retry Policy

If SplashPay does not receive a successful response (HTTP 200), the webhook will be retried automatically.

Attempt	Delay
1	Immediately
2	1 minute
3	5 minutes
4	15 minutes
5	30 minutes
6	1 hour
7	6 hours
8	24 hours

After the final retry, the webhook is marked as failed.

Best Practices

Always verify signatures

Reject webhook requests with invalid signatures.

Process asynchronously

Respond with HTTP 200 immediately, then process the webhook in the background.

Use idempotent processing

The same webhook may be delivered more than once. Use the payment reference to avoid duplicate processing.

Store provider references

Persist both the merchant reference and provider reference for reconciliation.

Do not trust browser redirects

Always rely on webhooks to determine the final payment status.

Event Lifecycle

Payment Created
      │
      ▼
Customer Pays
      │
      ▼
SplashPay
      │
      ▼
Webhook Sent
      │
      ▼
Merchant Server
      │
      ▼
HTTP 200 OK

Testing Webhooks

During development you can expose your local server using tools such as:

ngrok
Cloudflare Tunnel
LocalTunnel

Example:

https://abc123.ngrok.io/webhooks/splashpay

Supported Payment Methods

Webhooks are sent for all SplashPay collection methods:

Mobile Money
Card Payments
Dynamic TANQR

Next Steps

Payment Status

Retrieve the latest status of any payment.

Collections Overview

Learn more about SplashPay Collections.

Getting Started

Collections

Disbursements

Webhooks

Webhooks

Real-time Notifications

Configure Your Webhook URL

Webhook Events

Sample Webhook

Webhook Payload

Verify Webhook Signature

Example Verification (PHP)

Example Verification (Node.js)

Return HTTP 200

Retry Policy

Best Practices

Event Lifecycle

Testing Webhooks

Supported Payment Methods

Next Steps

Payment Status

Collections Overview

​Webhooks

Real-time Notifications

​Configure Your Webhook URL

​Webhook Events

​Sample Webhook

​Webhook Payload

​Verify Webhook Signature

​Example Verification (PHP)

​Example Verification (Node.js)

​Return HTTP 200

​Retry Policy

​Best Practices

​Event Lifecycle

​Testing Webhooks

​Supported Payment Methods

​Next Steps

Payment Status

Collections Overview

Webhooks

Configure Your Webhook URL

Webhook Events

Sample Webhook

Webhook Payload

Verify Webhook Signature

Example Verification (PHP)

Example Verification (Node.js)

Return HTTP 200

Retry Policy

Best Practices

Event Lifecycle

Testing Webhooks

Supported Payment Methods

Next Steps