Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payfonte.com/llms.txt

Use this file to discover all available pages before exploring further.

Payfonte sends webhook events when disbursement status changes (for example processing, success, failed). Use webhooks as your primary asynchronous disbursement update channel.

​
Webhook Source IPs

If you restrict inbound traffic by IP address, allowlist the following Payfonte webhook source IPs for each environment.
EnvironmentSource IPs
Production49.13.133.127, 49.13.229.61, 194.32.79.135
Sandbox49.12.224.228, 49.13.224.113

​
Payload Fields

FieldDescription
eventEvent type (for example disbursement.status)
clientIdYour Payfonte client ID
data.statusdisbursement status (processing, success, failed)
data.statusDescriptionProvider/platform status detail
data.referencePayfonte disbursement reference
data.externalReferenceMerchant-provided reference
data.providersReferenceProvider reference
data.amountdisbursement amount in minor units
data.chargeApplied disbursement charge
data.providerProvider slug used
data.transferRecipientIdRecipient identifier
data.transferRecipientLabelHuman-readable recipient label
deliveryIdWebhook delivery identifier
Sample payload:
disbursement.status
{
  "event": "disbursement.status",
  "clientId": "payfusion",
  "data": {
    "clientId": "payfusion",
    "type": "disbursement",
    "status": "success",
    "statusDescription": "Disbursement was successful",
    "reference": "L20250614142024AAAAA",
    "providersReference": "reference-from-mno",
    "externalReference": "merchant-reference",
    "currency": "XOF",
    "country": "BJ",
    "transferRecipientId": "684d561743dac722bcd43e9f",
    "transferRecipientLabel": "MTN MoMo | 2290123456789",
    "charge": 180,
    "amount": 10000,
    "provider": "mtn-momo-benin",
    "providerLabel": "MTN MoMo",
    "providerLogo": "https://payfonte.s3.amazonaws.com/mtn-momo.png",
    "channel": "mobile-money",
    "timestamp": "2025-06-14T14:20:25.023Z",
    "narration": "disbursement narration here",
    "completedAt": 1749910827
  },
  "deliveryId": "684d852b27e08e60f4d09103"
}

​
Signature Verification

Validate webhook authenticity before processing.
  • Header: x-webhook-signature
  • Algorithm: sha512 HMAC of request body using your client-secret
const crypto = require("crypto");

app.post("/payfonte/disbursement-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");
  }

  res.status(200).send("OK");
  processDisbursementWebhook(req.body);
});

​
Safe Processing Pattern

1

Acknowledge quickly

Return HTTP 200 immediately after basic validation.
2

Check idempotency

Deduplicate by reference + status (or deliveryId) before applying business actions.
3

Update internal ledger/state

Mark disbursement as final only for terminal statuses and save statusDescription.
4

Verify for critical disbursements

Optionally confirm final state using GET /billing/v1/disbursements/verify/{reference}.

​
Common Issues

IssueLikely CauseFix
Duplicate webhook processingNo idempotency handlingStore processed reference/status and skip repeats
Signature mismatchWrong secret or mutated payloadUse correct client-secret and hash exact request body
Missed status updatesTimeout/non-200 responsesReturn 200 quickly; move heavy logic to async worker
Conflicting disbursement stateOut-of-order processingAlways compare current state before applying updates

Disbursements Overview

End-to-end disbursement flow and endpoints.

Disbursement Examples

Request/response payload samples.

Authorization Mode

PIN vs Authorization URL configuration.