Nile Pay Docs

Generate payment links (invoices) to share with customers via SMS, email, or messaging apps.

Overview

Payment links allow customers to pay without integrating directly into your app. Create an invoice, share the generated URL, and receive payment notifications via webhook.

Flow

Create invoice via SDK with amount and reference
Receive invoice with payment URL
Share URL with customer (SMS, email, messaging)
Customer clicks link, lands on hosted payment page
Customer enters phone, selects payment method, completes payment
Real-time status update sent to your webhook

Creating an Invoice

import { createNilePay } from '@nilepay/sdk';

const nilePay = createNilePay({
  environment: 'sandbox', // or 'live'
  apiKey: 'npk_sandbox_your_key',
  apiSecret: 'nps_sandbox_your_secret',
});

const invoice = await nilePay.createInvoice({
  amount: 50000,
  currency: 'UGX',
  reference: 'ORDER-001',
  description: 'Premium subscription - Monthly',
  customer: {
    phone: '+256700000000',
    email: 'customer@example.com',
    name: 'John Doe',
  },
  dueDate: '2026-04-15T23:59:59Z',
  metadata: {
    orderId: '12345',
    plan: 'premium-monthly',
  },
});

console.log(invoice.paymentUrl);
// https://nilepay.nilesquad.com/pay?token=inv_abc123xyz

Invoice Response

{
  invoiceId: 'inv_abc123xyz',
  paymentUrl: 'https://nilepay.nilesquad.com/pay?token=inv_abc123xyz',
  reference: 'ORDER-001',
  amount: 50000,
  currency: 'UGX',
  status: 'pending',
  expiresAt: '2026-04-15T23:59:59Z',
  createdAt: '2026-04-01T10:00:00Z',
}

Hosted Payment Page

The payment page (nilepay.nilesquad.com/pay?token=...) handles:

Mobile money method selection (MTN, Airtel Money)
Customer phone number entry
USSD push or STK push initiation
Real-time status polling
Success/failure confirmation screen

No additional integration required. The page is hosted and maintained by Nile Pay.

Customer Flow

Step	Customer Action
1	Click payment link
2	Review amount and description
3	Enter or confirm phone number
4	Select payment method
5	Approve payment on their phone
6	See confirmation on payment page

Checking Invoice Status

Query invoice status at any time:

const status = await nilePay.getStatus({
  reference: 'ORDER-001',
});

console.log(status.status);
// 'pending' | 'processing' | 'successful' | 'failed' | 'cancelled'

Real-Time Updates

Configure webhooks to receive instant status updates:

// Your webhook handler receives:
{
  event: 'success',
  transactionId: 'txn_abc123',
  reference: 'ORDER-001',
  status: 'successful',
  amount: 50000,
  currency: 'UGX',
  // ... additional fields
}

See the Webhooks guide for signature verification and handling best practices.

Expiration

Invoices expire based on the dueDate parameter. Expired invoices cannot be paid. Set an appropriate expiration for your use case:

Product purchases: 24-48 hours
Service payments: 7-30 days
Subscriptions: Match billing cycle

Payment Links