Quick Start

Nylon Pay runs in two modes. In sandbox you test with simulated payments and no real money. In live you accept real payments. You start in sandbox, do your whole integration, then go live when you are ready.

Here is the whole journey, end to end. If you only want the code, jump to Make your first payment.

1. Create your account

Go to nylonpay.nilesquad.com and sign up with your name, email, password, and company name. Verify the code that is emailed to you.

No payment or ID is required to sign up. You are in sandbox immediately.

2. Create a collection account

Go to Accounts in the dashboard and click Create Account. Give it a name, for example My Business Account.

A collection account holds incoming payments before settlement.

3. Create your sandbox API keys

API keys are how the SDK identifies you to Nylon Pay.

• Go to Settings > API Keys in the dashboard
• Click Create Key
• Copy your apiKey and apiSecret immediately. The secret is shown only once

Sandbox keys look like this:

apiKey:    npk_test_...
apiSecret: nps_test_...

Live keys follow the same process, but require Level 1 KYC approval first. Sandbox keys start with npk_test_, live keys with npk_live_. The prefix is how Nylon Pay knows which mode a key belongs to.

4. Install the SDK

Requirements

TypeScript:

• Node.js v18 or higher
• Server-side only (not for browsers)

Python:

• Python 3.10 or higher
• Server-side only (not for browsers)

PHP:

• PHP 8.1 or higher (ext-curl, ext-json, ext-openssl, ext-mbstring)
• Server-side only (not for browsers)

Installation

npm install @nile-squad/nylonpay-ts

Initialize the client

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

Test vs live mode is selected by your API key. A sandbox key runs in the test environment. A live key processes real money.

The global onError handler is registered before any payment call. It receives structured errors from operations on this client. NETWORK means this machine is offline. SERVICES_DOWN means Nylon Pay did not complete the request.

5. Make your first payment

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

// 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('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

1. Request sent: your server starts a collection with the SDK
2. Customer prompt: the customer gets a phone prompt to approve the payment
3. Confirmation: the customer enters their PIN
4. Result: the SDK emits success or failed, and you can also listen for webhooks

Payment options

Required fields

Optional fields

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 behavior

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

Pass testOutcome: 'fail' or a Nylon failure code to force the failure path, or 'success' for the happy path. Omit it and the sandbox succeeds about 70% of the time. 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.

Next steps

• Merchant Onboarding, submit free KYC and go live
• SDK Reference, all methods and options
• Webhooks, receive payment notifications
• Coverage, check what is supported where