Nile Pay Docs

This guide walks through a complete payment flow from initialization to event handling.

Complete Example

import { createNilePay } from "@nilepay/sdk";
import { randomUUID } from "crypto";

const nilePay = createNilePay({
  environment: "sandbox",
  apiKey: "npk_sandbox_...",
  apiSecret: "nps_sandbox_...",
});

// Start a payment
const payment = await nilePay.collectPayment({
  amount: 5000,
  currency: "UGX",
  customer: { phone: "256700000000" },
  reference: randomUUID(),
  description: "Order #1234",
});

// Listen for status updates
payment.on("processing", (data) => {
  console.log("Payment processing...", data.reference);
});

payment.on("success", (data) => {
  console.log("Payment successful!", data.transactionId);
});

payment.on("failed", (data) => {
  console.log("Payment failed:", data.message);
});

// Or use promise-based waiting
const result = await payment.wait();

How It Works

Request sent: SDK authenticates with HMAC-SHA256 and sends payment request to Nile Pay backend
Processing: Backend forwards to provider (MTN MoMo, Airtel Money, etc.)
Customer action: Provider sends USSD prompt to customer's phone
Confirmation: Customer enters PIN on their phone
Webhook: Provider confirms to Nile Pay
Events: SDK emits success or failed based on outcome

Payment Options

Required Fields

Field	Type	Description
`amount`	number	Amount in smallest currency unit (UGX = cents)
`currency`	string	ISO 4217 currency code (e.g., "UGX")
`customer.phone`	string	Customer phone number with country code
`reference`	string	Unique order reference (UUID recommended)

Optional Fields

Field	Type	Description
`description`	string	Payment description shown to customer
`customer.name`	string	Customer full name
`customer.email`	string	Customer email address
`metadata`	object	Custom key-value pairs for your records

Event Handling

EventEmitter Pattern

payment.on("processing", handler);
payment.on("success", handler);
payment.on("failed", handler);
payment.on("cancelled", handler);

Promise Pattern

const result = await payment.wait();

// result.status: true with data, or false with message
if (result.status) {
  console.log(result.data.transactionId);
} else {
  console.error(result.message);
}

Sandbox Mode

Sandbox mode simulates the payment flow without charging real money. Use test phone numbers and expect consistent responses for testing your integration.

Idempotency

Use a UUID v4 as your reference to ensure payment requests are idempotent. If a request is retried, the same reference returns the existing payment status instead of creating duplicates.

Your First Payment