Nylon Pay Docs

createInvoice(request)

Creates an invoice, emails the customer, and returns a payment link. The customer opens the link to pay via mobile money.

const result = await nylonpay.createInvoice(request);

Request Fields

Field	Type	Required	Description
`amount`	`number`	yes	Invoice amount in smallest currency unit
`currency`	`Currency`	yes	ISO 4217 currency code (e.g., `"UGX"`)
`customerEmail`	`string`	yes	Customer email address - invoice is sent here
`customerName`	`string`	no	Customer display name shown on the invoice
`customerPhone`	`string`	no	Pre-fills the phone field on the payment page
`description`	`string`	no	Invoice description
`dueDate`	`string`	no	ISO 8601 date string (e.g. `"2025-12-31"`)
`items`	`InvoiceItem[]`	no	Line items for the invoice
`merchantReference`	`string`	no	Stored on the transaction for your reconciliation
`metadata`	`Record<string, string>`	no	Custom key-value pairs for your records

Response

interface InvoiceResponse {
  id: string;
  invoiceNumber: string;
  paymentLink: string;
  amount: string;
  currency: string;
  status: string;
}

Example

import { createNylonPay } from '@nile-squad/nylonpay-ts';

const nylonpay = createNylonPay({
  apiKey: 'npk_test_...',
  apiSecret: 'nps_test_...',
});

const result = await nylonpay.createInvoice({
  amount: 150000,
  currency: 'UGX',
  customerEmail: 'customer@example.com',
  customerName: 'John Doe',
  description: 'Premium Subscription - Annual',
  metadata: { plan: 'premium_annual' },
});

if (result.isOk) {
  const { invoiceNumber, paymentLink } = result.value;

  console.log(`Invoice ${invoiceNumber}`);
  console.log(`Payment link: ${paymentLink}`);
} else {
  console.error('Failed to create invoice:', result.error);
}

Invoice Flow

createInvoice() -> Customer receives invoice email
                              |
                   Customer opens payment link
                              |
                  Hosted page: enter phone number
                              |
                  Customer approves on their phone
                              |
              Webhook notification + receipt email sent

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
Request payment: Ask another user to pay you

The paymentLink directs the customer to a Nylon Pay-hosted page where they enter their mobile money phone number and complete payment via a phone prompt. A receipt is sent to the customer automatically after a successful payment.

Tracking Invoice Status

Listen for webhook events to know when a customer pays. The transaction.successful event fires when the payment succeeds.

// Verify and handle the webhook in your endpoint
const verified = nylonpay.verifyWebhookSignature({
  payload: rawBody,
  signature: req.headers['x-nylon-signature'],
  secret: process.env.WEBHOOK_SECRET,
});

if (verified) {
  const body = JSON.parse(rawBody);
  if (body.event === 'transaction.successful') {
    console.log('Invoice paid:', body.payload.reference);
  }
}

Invoices