Nile Pay Docs

createInvoice(request)

Creates an invoice and returns a payment link. The customer pays via Nile Pay's hosted payment page.

const result = await nile.createInvoice(request);

Request Fields

Field	Type	Required	Description
`amount`	`number`	yes	Invoice amount in smallest currency unit
`currency`	`string`	no	ISO 4217 currency code. Default: `"UGX"`
`description`	`string`	no	Invoice description
`customer.phone`	`string`	no	Customer phone number
`customer.email`	`string`	no	Customer email address
`customer.name`	`string`	no	Customer name
`reference`	`string`	yes	UUID v4 for idempotency
`dueDate`	`string`	no	ISO 8601 date string
`metadata`	`Record<string, unknown>`	no	Custom data

Response

interface InvoiceResponse {
  invoiceId: string;
  paymentLink: string;    // URL for hosted payment page
  reference: string;
  amount: number;
  currency: string;
  status: "pending" | "paid" | "expired";
  createdAt: string;
}

Example

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

const nile = createNilePay({
  environment: "sandbox",
  apiKey: "npk_test_...",
  apiSecret: "nps_test_...",
});

const result = await nile.createInvoice({
  amount: 150000,
  currency: "UGX",
  description: "Premium Subscription - Annual",
  customer: {
    name: "John Doe",
    email: "john@example.com",
    phone: "+256700000000",
  },
  reference: crypto.randomUUID(),
  dueDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days
  metadata: { plan: "premium_annual" },
});

if (result.status) {
  const { invoiceId, paymentLink } = result.data;
  
  console.log(`Invoice ${invoiceId}`);
  console.log(`Payment link: ${paymentLink}`);
  
  // Send link to customer via email/SMS
  await sendPaymentLink(result.data.customer.email, paymentLink);
} else {
  console.error("Failed to create invoice:", result.message);
}

Invoice Flow

createInvoice() → Get paymentLink → Send to customer
                                         ↓
                              Customer opens link
                                         ↓
                         Hosted payment page (mobile money)
                                         ↓
                              Payment processed
                                         ↓
                              Webhook / getStatus()

Use Cases

Bill presentation: Send an invoice link to customers instead of collecting immediately
Multi-step checkout: Generate a link after cart review
Recurring billing: Create invoices on a schedule
Send money: Request payment from another user

Hosted Payment Page

The paymentLink opens Nile Pay's hosted page where customers:

Select payment method (Mobile Money)
Enter PIN on their phone
Receive confirmation

After payment, the customer sees a success page. Your webhook receives the notification.

Tracking Invoice Status

// Poll status
const result = await nile.getStatus({ reference: invoiceReference });

// Or use events if you need real-time updates
// (Invoices can be tracked via PaymentInstance events)

Invoices

On this page