JGME Pay
Collect Payment

Webhooks and Callbacks

Receive and verify real-time collection payment updates from JGME Pay.

JGME Pay 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 JGME Pay webhook source IPs for each environment.

EnvironmentSource IPs
Production49.13.133.127, 49.13.229.61, 194.32.79.135

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

FieldDescription
eventEvent type (for example payment.completed)
clientIdYour JGME Pay client identifier
data.statusTransaction status (success, failed, or pending)
data.referenceJGME Pay transaction reference
data.externalReferenceMerchant-provided reference (if supplied)
data.amountTransaction amount in minor units
data.chargeApplied transaction charge
data.providerProvider slug/name used for processing
data.channelPayment channel (for example card, mobile-money)
data.userCustomer 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/jgmepay?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("/jgmepay/webhook", express.json({ type: "*/*" }), (req, res) => {
  const secret = process.env.JGME_PAY_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

JGME Pay uses webhook URLs in this order:

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

Common Issues

IssueLikely CauseFix
Duplicate webhook processingNo idempotency guardTrack processed reference + status and skip repeats
Signature mismatchWrong secret or payload mutationUse correct client-secret and hash the exact received body
Missed updatesEndpoint timeout/non-200 responsesReturn 200 quickly and move heavy work to async workers
Wrong environment eventsMismatched environment setupUse matching endpoint and credentials per environment

On this page