Webhooks & partner integrations

Couriers and payment providers integrate with nxtPay through adapters: nxtPay calls your API to start work, and you notify nxtPay when something changes.

Courier partners

When a merchant sends an order with your service, nxtPay books it through your API with the pickup (shop) and drop-off (shopper) details. You then post status updates to:

POST https://pay.nxtlaunch.tech/api/delivery/webhook/{your-partner-code}

Statuses

Status	Meaning
`accepted`	A rider is assigned (send rider name, phone, ETA)
`picked_up`	Collected from the shop
`in_transit`	On the way to the shopper
`delivered`	Handed over: must include the shopper's 4-digit hand-over code
`failed` / `cancelled`	Couldn't deliver: include a reason; the order returns to the merchant to resend

Example

{
  "event_id": "evt_01J9Z...",
  "tracking_reference": "BEX-48213",
  "status": "delivered",
  "handover_code": "4821",
  "rider": { "name": "Musa K.", "phone": "256700111222" },
  "occurred_at": "2026-10-10T09:42:00+03:00"
}

Rules

Signatures: every request must be signed; unsigned or invalid requests are rejected with 401. Signing keys are exchanged during partner onboarding.
Idempotency: send a unique event_id; repeats are ignored safely.
Proof of delivery: delivered with a wrong code is refused (5 wrong tries lock it for 30 minutes). The code is shown only to the shopper.

Payment providers

Providers notify /api/payments/webhook/{provider}. Notifications are hints only: nxtPay always confirms the outcome through the provider's status API before settling. Pesapal is integrated; MTN MoMo and Airtel Money direct APIs and Uganda's National Payment Switch are next.

Merchant webhooks (coming with the Merchant API)

Merchants will receive signed events such as order.paid and order.refunded. See Merchant API → Webhooks.