Nile Pay Docs

collectPayment(request)

Initiates a payment collection and returns a PaymentInstance immediately. The instance is not a promise, it provides event listeners for real-time status updates.

const payment = nile.collectPayment(request);

Request Fields

Field	Type	Required	Description
`amount`	`number`	yes	Payment amount in smallest currency unit (e.g., UGX cents)
`currency`	`string`	no	ISO 4217 currency code. Default: `"UGX"`
`method`	`string`	no	Specific payment method to use
`description`	`string`	no	Payment description shown to customer
`customer.phone`	`string`	yes	Customer phone number (E.164 format recommended)
`customer.email`	`string`	no	Customer email address
`reference`	`string`	yes	UUID v4 for idempotency. Same reference = same payment
`invoiceNumber`	`string`	no	Your invoice/bill number
`notifyMerchant`	`boolean`	no	Send notification to merchant on completion. Default: `true`
`metadata`	`Record<string, unknown>`	no	Custom data attached to the transaction

Example

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

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

const payment = nile.collectPayment({
  amount: 50000, // 500 UGX
  currency: "UGX",
  description: "Order #12345",
  customer: {
    phone: "+256700000000",
    email: "customer@example.com",
  },
  reference: crypto.randomUUID(), // Required for idempotency
  invoiceNumber: "INV-2024-001",
  metadata: {
    orderId: "12345",
    items: 3,
  },
});

payment.on("success", (tx) => {
  console.log("Payment completed:", tx.transactionId);
});

Payment Flow

Your Server → Nile Pay Backend → Payment Provider → Customer Phone
                                                            ↓
    ← ← ← ← ← ← ← ← ← ← Status Updates ← ← ← ← ← ← ← ← ← ←
         ↓               ↓               ↓
    processing      success/failed     cancelled

You call collectPayment() with customer details and amount
SDK sends request to Nile Pay backend
Backend initiates payment with provider (e.g., Mobile Money)
Customer receives payment prompt on their phone
SDK polls getStatus() internally until terminal state
Events fire as status changes

Idempotency

The reference field is critical for idempotency. If a request fails mid-flight and you retry with the same reference, the SDK recognizes it as a duplicate and returns the existing payment instance.

Always generate a fresh UUID v4 for each new payment:

const reference = crypto.randomUUID(); // Node.js 19+

Return Value

collectPayment() returns a PaymentInstance immediately (synchronously). The instance is event-driven, use .on() to listen for status changes or .wait() to await completion.

See Payment Events for event handling patterns.

Collect Payment