Nylon Pay Docs

Prerequisites: You have already installed the SDK and have your sandbox API keys.

Complete Example

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

const nylonpay = createNylonPay({
  apiKey: 'npk_sandbox_...',
  apiSecret: 'nps_sandbox_...',
});

// Start a payment
const payment = await nylonpay.collectPayment({
  amount: 5000,
  currency: 'UGX',
  customer: { name: 'John Doe', phoneNumber: '256700000000' },
  description: 'Order #1234',
  reference: crypto.randomUUID(),
});

// Listen for status updates
payment.on('processing', ({ transaction }) => {
  console.log('Payment processing...', transaction?.reference);
});

payment.on('processing', () => {
  console.log('Awaiting customer PIN...');
});

payment.on('success', ({ transaction }) => {
  console.log('Payment successful!', transaction?.id);
});

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

// Or use promise-based waiting
const result = await payment.wait();

How It Works

Request sent: SDK authenticates and sends payment request to Nylon Pay backend
Processing: Backend forwards to provider (MTN MoMo, Airtel Money, etc.)
Customer action: Provider sends USSD/STK prompt to customer's phone
Confirmation: Customer enters PIN on their phone
Webhook: Provider confirms to Nylon Pay
Events: SDK emits success or failed based on outcome

Payment Options

Required Fields

Field	Type	Description
`amount`	number	Amount in smallest currency unit (UGX = cents)
`currency`	string	ISO 4217 currency code (e.g., "UGX")
`customer.name`	string	Customer full name
`customer.phoneNumber`	string	Customer phone number with country code (e.g., `+256...`)
`description`	string	Payment description shown to customer

Optional Fields

Field	Type	Description
`reference`	`string`	no
`customer.email`	string	Customer email address
`metadata`	object	Custom key-value pairs for your records

Event Handling

EventEmitter Pattern

payment.on('processing', handler);
payment.on('success', handler);
payment.on('failed', handler);
payment.on('cancelled', handler);

Promise Pattern

try {
  const transaction = await payment.wait();
  console.log('Payment successful:', transaction.id);
} catch (error) {
  console.error('Payment failed:', error);
}

Sandbox Mode

Sandbox mode simulates the payments flow without charging real money. Use test phone numbers and expect consistent responses for testing your integration.

See Testing guide for how to simulate different outcomes (success, failure, timeout).

Idempotency

The reference field prevents duplicate charges. If a request fails and you retry with the same reference, the SDK returns the existing payment 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.

Your First Payment