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_test_...',
  apiSecret: 'nps_test_...',
});

// 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: Your server starts a collection with the SDK
Customer prompt: The customer gets a phone prompt to approve the payment
Confirmation: The customer enters their PIN
Result: The SDK emits success or failed, and you can also listen for webhooks

Payment Options

Required Fields

Field	Type	Description
`amount`	number	Amount in smallest currency unit (for UGX, whole shillings)
`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	Unique reference (any valid UUID). Auto-generated as UUID v4 if omitted
`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

const transaction = await payment.wait();
if (transaction) {
  console.log('Payment successful:', transaction.id);
} else {
  console.log('Payment failed or timed out');
}

Sandbox Mode

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

Use your sandbox API key to exercise success and failure paths without moving real money. Pass testOutcome: 'fail' to force the failure path or 'success' for the happy path. Omit it for a random result. testOutcome only works with a sandbox key.

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