Webhooks and Callbacks

Payfonte sends webhook events to your configured endpoint when payment state changes. Use webhooks as your primary source of truth for asynchronous payment outcomes.

Webhook Source IPs

If you restrict inbound traffic by IP address, allowlist the following Payfonte webhook source IPs for each environment.

Environment	Source IPs
Production	`49.13.133.127`, `49.13.229.61`, `194.32.79.135`
Sandbox	`49.12.224.228`, `49.13.224.113`

Why Webhooks Matter

Real-Time Updates

Get payment updates without polling every transaction.

Reliable Completion

Confirm final status (success or failed) before fulfilling orders.

Operational Safety

Handle retries with idempotent processing to avoid duplicate fulfillment.

Webhook Payload Fields

Field	Description
`event`	Event type (for example `payment.completed`)
`clientId`	Your Payfonte client identifier
`data.status`	Transaction status (`success`, `failed`, or `pending`)
`data.reference`	Payfonte transaction reference
`data.externalReference`	Merchant-provided reference (if supplied)
`data.amount`	Transaction amount in minor units
`data.charge`	Applied transaction charge
`data.provider`	Provider slug/name used for processing
`data.channel`	Payment channel (for example `card`, `mobile-money`)
`data.user`	Customer metadata (name/email/phone when available)

Sample payload:

payment.completed

{
  "clientId": "solara_textiles",
  "data": {
    "amount": 74250,
    "channel": "mobile-money",
    "charge": 1856,
    "clientId": "solara_textiles",
    "completedAt": "2026-05-08T09:24:51.127Z",
    "country": "SN",
    "currency": "XOF",
    "externalReference": "ord_8473926150",
    "id": "7f24c91a6b8e45d2f1309c7a",
    "locale": "en",
    "metadata": {},
    "paidAt": 1778232291,
    "paymentReference": "PF20260508092451QZRM4",
    "platformReference": "7f24c91a6b8e45d2f1309c7a",
    "provider": "wave-senegal",
    "reference": "PF20260508092451QZRM4",
    "status": "success",
    "statusDescription": "succeeded",
    "user": {
      "phoneNumber": "221771234589"
    }
  },
  "deliveryId": "7f24c923bb1d0e4a9c8156fd",
  "event": "payment.completed",
  "reference": "PF20260508092451QZRM4",
  "webhook": "https://merchant.example.com/webhooks/payfonte?client_id=solara_textiles"
}

Signature Verification (Required)

Every webhook includes:

Header: x-webhook-signature
Value: sha512 HMAC digest of raw request body, signed with your client-secret

Use your client-secret from Settings -> Security -> API Keys and Webhooks.

const crypto = require("crypto");

app.post("/payfonte/webhook", express.json({ type: "*/*" }), (req, res) => {
  const secret = process.env.PAYFONTE_CLIENT_SECRET;
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac("sha512", secret)
    .update(payload)
    .digest("hex");
  const received = req.headers["x-webhook-signature"];

  if (expected !== received) {
    return res.status(401).send("Invalid signature");
  }

  // Acknowledge quickly, then process asynchronously.
  res.status(200).send("OK");
  processWebhook(req.body);
});

If signature validation fails, do not process the event.

Idempotent Processing Pattern

Acknowledge fast

Return HTTP 200 quickly to prevent unnecessary retries.

Check duplicates

Use reference + status (or a delivery identifier if available) to detect already-processed events.

Verify transaction when needed

For critical flows, verify payment status from your backend before final fulfillment.

Apply state transition safely

Ensure business actions (for example order fulfillment) run once per final success.

Webhook URL Priority

Payfonte uses webhook URLs in this order:

Webhook URL passed in the checkout/direct-charge request (webhook)
Webhook URL configured on the provider integration
Webhook URL configured in dashboard settings

Common Issues

Issue	Likely Cause	Fix
Duplicate webhook processing	No idempotency guard	Track processed `reference` + `status` and skip repeats
Signature mismatch	Wrong secret or payload mutation	Use correct `client-secret` and hash the exact received body
Missed updates	Endpoint timeout/non-200 responses	Return `200` quickly and move heavy work to async workers
Wrong environment events	Mixed sandbox/production setup	Use matching endpoint and credentials per environment

Standard Checkout

Redirect flow with webhook completion.

Direct Charge API

Direct charge flow and action handling.

Authorization

Credential and header requirements.

Getting Started

Core Concepts

Providers & Coverage

Development

Collect Payment

Disbursements

Webhooks and Callbacks

Webhook Source IPs

Why Webhooks Matter

Real-Time Updates

Reliable Completion

Operational Safety

Webhook Payload Fields

Signature Verification (Required)

Idempotent Processing Pattern

Webhook URL Priority

Common Issues

Standard Checkout

Direct Charge API

Authorization

​Webhook Source IPs

​Why Webhooks Matter

Real-Time Updates

Reliable Completion

Operational Safety

​Webhook Payload Fields

​Signature Verification (Required)

​Idempotent Processing Pattern

​Webhook URL Priority

​Common Issues

​Related Docs

Standard Checkout

Direct Charge API

Authorization

Webhook Source IPs

Why Webhooks Matter

Webhook Payload Fields

Signature Verification (Required)

Idempotent Processing Pattern

Webhook URL Priority

Common Issues

Related Docs