Early access · specification may change

Merchant API

Let shoppers pay with nxtPay (pay in 4 or in full) on your own website or app. You create a checkout session, send the shopper to nxtPay to sign and pay, and receive a signed webhook when the order is paid. You're settled like any nxtPay sale.

Authentication

Use your secret key as a Bearer token from your server. Keys are per environment:

Authorization: Bearer sk_test_51Jd...   # sandbox
Authorization: Bearer sk_live_51Jd...   # live

Base URL (planned): https://api.nxtlaunch.tech/v1. Never put secret keys in a browser or mobile app.

Create a checkout session

POST /v1/checkout_sessions
Idempotency-Key: 6f1c...                       # safe retries

{
  "reference": "ORDER-10045",                   # your order id
  "currency": "UGX",
  "items": [
    { "name": "43-inch smart TV", "sku": "TV-43", "quantity": 1, "unit_amount": 1150000 }
  ],
  "fulfilment": { "method": "delivery", "address": "Plot 4, Ntinda Road, Kampala" },
  "customer": { "phone": "256772123456" },      # optional prefill
  "success_url": "https://shop.example/thanks?ref=ORDER-10045",
  "cancel_url": "https://shop.example/cart"
}

Response:

{
  "id": "cs_test_a1B2c3",
  "status": "open",                  # open | completed | expired
  "url": "https://pay.nxtlaunch.tech/checkout/cs_test_a1B2c3",
  "amount_total": 1150000,
  "expires_at": "2026-10-10T10:30:00+03:00"
}

Redirect the shopper to url. They sign in, choose pay in 4 or in full, sign with their PIN, and pay. They return to success_url; rely on the webhook, not the redirect, to fulfil the order.

Other endpoints

Endpoint	Purpose
`GET /v1/checkout_sessions/{id}`	Session status and resulting order
`GET /v1/orders/{id}`	Order with items, payment method, status, delivery
`POST /v1/orders/{id}/dispatch`	Mark shipped / book a courier
`POST /v1/refunds`	Refund an order after an accepted return (closes the shopper's plan)
`POST /v1/in_store_sales`	Create a counter sale (QR / code) from your POS

Webhooks

Configure an HTTPS endpoint; nxtPay sends events with a signature header:

Nxtpay-Signature: t=1760088000,v1=5257a869e7ec...   # HMAC-SHA256 of "t.body" with your webhook secret

Event	When
`checkout.session.completed`	Shopper signed and paid (25% or full)
`order.paid`	Order is paid and ready to fulfil
`order.delivered`	Delivered (hand-over code confirmed) or collected
`order.refunded`	Refund completed
`payout.paid`	Your weekly payout was sent

Verify the signature, reject events older than 5 minutes, respond 2xx quickly, and handle duplicates by event id. Failed deliveries are retried with backoff for 24 hours.

Errors

HTTP 422
{ "error": { "type": "invalid_request", "code": "amount_too_low", "message": "Minimum order is UGX 10,000." } }

Request early access

Tell us about your store or platform. Early-access partners get sandbox keys, a direct line to our engineers and input on the API.