Nylon Pay Docs

collectPayment(request)

Initiates a payment collection and returns a PaymentInstance immediately. Use the event listeners to track status changes in real time.

const payment = await nylonpay.collectPayment(request);

Request Fields

Field	Type	Required	Description
`amount`	`number`	yes	Payment amount in smallest currency unit. Minimum 500 UGX
`currency`	`Currency`	yes	ISO 4217 currency code (e.g., `"UGX"`)
`description`	`string`	yes	Payment description shown to customer
`customer.name`	`string`	yes	Customer full name
`customer.phoneNumber`	`string`	yes	Customer phone number. Any common format accepted, auto-normalized to `256XXXXXXXXX`. See Phone Number Format
`customer.email`	`string`	no	Customer email address
`method`	`PaymentMethod`	no	Specific payment method to use (`"mobileMoney"` or `"bank"`)
`reference`	`string`	no	Unique reference (any valid UUID). Auto-generated as UUID v4 if omitted
`metadata`	`Record<string, string>`	no	Custom key-value pairs attached to the transaction

Example

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

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

const payment = await nylonpay.collectPayment({
  amount: 50000,
  currency: 'UGX',
  description: 'Order #12345',
  customer: {
    name: 'John Doe',
    phoneNumber: '+256700000000',
    email: 'customer@example.com',
  },
  reference: '550e8400-e29b-41d4-a716-446655440000', // UUID (any version accepted)
  metadata: {
    orderId: '12345',
    items: '3',
  },
});

payment.on('success', ({ transaction }) => {
  console.log('Payment completed:', transaction.id);
});

Payment Flow

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

You call collectPayment() with customer details and amount
SDK sends request to Nylon Pay backend
Backend initiates payment with provider (e.g., Mobile Money)
Customer receives payment prompt on their phone
SDK tracks the payment status automatically
Events fire as status changes (processing, success/failed)

Idempotency

The reference field prevents duplicate charges. If a request fails and you retry with the same reference, the SDK returns the existing payment instance instead of creating a new one.

A supplied reference must be a valid UUID of any version. The SDK generates a UUID v4 when you omit reference. Never reuse the same reference for different payments.

Return Value

collectPayment() returns a PaymentInstance with:

Method	Description
`.on(event, handler)`	Listen for events (`processing`, `success`, `failed`, `cancelled`, `error`)
`.once(event, handler)`	Listen once, then auto-remove
`.off(event, handler)`	Remove a handler
`.wait()`	Promise that resolves `Transaction` on success, `null` on failure/cancel/error. Never rejects.
`.reference`	The transaction reference
`.status`	Current transaction status

Collect Payment