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 the market's calling code (`256…` for UGX, `254…` for KES). 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
`tags`	`string[]`	no	Up to 10 business labels for filtering. See Smart Tags
`testOutcome`	`"success"`, `"fail"`, or a Nylon failure code	no	Force the sandbox result while testing. Omit it and the sandbox picks success about 70% of the time. Sandbox keys only

Example

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

const nylonpay = createNylonPay({
  apiKey: 'npk_test_...',
  apiSecret: 'nps_test_...',
  onError: (error) => {
    if (error.reason === 'SERVICES_DOWN') {
      console.error('Pause payment attempts:', error.message);
    }
  },
});

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);
});

While testing with a sandbox key, pass testOutcome to force a result. Use "success" to walk the happy path and "fail" or a code such as "insufficient_balance" to walk the failure path, including webhooks and your event handlers. Forced fails are labelled Sandbox simulated:. Omit it and the sandbox succeeds about 70% of the time.

Sending testOutcome with a live key is rejected as a validation error, so remove it before going live.

const payment = await nylonpay.collectPayment({
  amount: 50000,
  currency: 'UGX',
  description: 'Order #12345',
  customer: {
    name: 'John Doe',
    phoneNumber: '+256700000000',
  },
  testOutcome: 'fail',
});

payment.on('failed', ({ error }) => {
  console.log('Payment failed as forced:', error);
});

Payment Flow

Call collectPayment() with the customer details and amount.
The customer receives a payment prompt on their phone.
The SDK reports processing, success, failed, or cancelled events.
Use wait() or webhooks when you need a final transaction state.

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