API Reference

Use the SDK, not direct REST API calls. The SDK handles signing, retries, types, and error handling automatically.

Installation

npm install @nile-squad/nylonpay-ts

Initialize

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

const nylonPay = createNylonPay({
  apiKey: 'npk_sandbox_your_key',
  apiSecret: 'nps_sandbox_your_secret'
})

Methods

`collectPayment()`

Collect a payment from a customer. Returns a PaymentInstance for event-driven status tracking.

const payment = await nylonPay.collectPayment({
  amount: 50000,                 // Required: smallest currency unit
  currency: 'UGX',               // Required: ISO 4217 code
  description: 'Product name',   // Required: description of payment
  customer: {
    name: 'John Doe',            // Required: customer name
    phoneNumber: '256700000000', // Required: no plus sign
    email: 'john@example.com'    // Optional
  },
  reference: crypto.randomUUID(),  // Optional: UUID, auto-generated as v4 if omitted
  metadata: {                    // Optional: your custom data
    orderId: '12345'
  }
})

// Use events or wait() to track payment status
payment.on('success', ({ transaction }) => {
  console.log('Transaction ID:', transaction?.id)
})

`createInvoice()`

Create a payment link (hosted payment page). Returns a Result.

const result = await nylonPay.createInvoice({
  amount: 50000,
  currency: 'UGX',
  customerEmail: 'customer@example.com',
  description: 'Premium subscription',
  items: [
    { name: 'Premium Plan', quantity: 1, amount: 50000 }
  ],
  metadata: {
    orderId: '12345'
  }
})

if (result.isOk) {
  console.log(result.value.paymentLink)
} else {
  console.error(result.error)
}

`getStatus()`

Check transaction status by reference.

const result = await nylonPay.getStatus({
  reference: crypto.randomUUID()  // UUID, the value returned from collectPayment()
})

if (result.isOk) {
  console.log(result.value.status)
  // 'pending' | 'processing' | 'successful' | 'failed' | 'cancelled'
} else {
  console.error(result.error)
}

`wait()`

Wait for a payment to complete (after collectPayment()).

const payment = await nylonPay.collectPayment({...})

const final = await payment.wait()
if (final) {
  console.log(final.status)
  // 'successful'
} else {
  // Payment failed, cancelled, or timed out
  console.error('Payment did not succeed')
}

Configuration Options

Test vs. live mode is selected by your API key, not by config. There is no environment option.

Option	Type	Default	Description
`apiKey`	string	required	Your API key
`apiSecret`	string	required	Your API secret
`timeoutMs`	number	`30000`	Request timeout in milliseconds
`maxRetries`	number	`3`	Retry attempts for failed requests
`maxPollDurationMs`	number	`300000`	Max wait time for `wait()` (5 min)

Error Handling Pattern

Methods that make HTTP requests return a Result object. Always check isOk before accessing value.

const result = await nylonPay.getStatus({ reference: crypto.randomUUID() })

if (result.isOk) {
  // Use result.value
  console.log(result.value.status)
} else {
  // Handle error
  console.error(result.error)
}

Common Error Codes

Code	Meaning
`HTTP_4XX`	Client error (bad request, unauthorized)
`HTTP_5XX`	Server error
`TIMEOUT`	Request timed out
`NETWORK_ERROR`	Connection failed
`INVALID_RESPONSE`	Unexpected response format
`RESPONSE_TAMPERED`	Response signature mismatch
`UNKNOWN`	Unexpected error

Environment Configuration

Environment	Value
Sandbox	`'sandbox'`
Live	`'live'`

Packages

Package	Description
`@nile-squad/nylonpay-ts`	TypeScript SDK for payments and invoices
`nylonpay-py`	Python SDK for payments and invoices

API Reference

On this page