Nylon Pay Docs

makePayout(request)

Initiates a payout and returns a PaymentInstance immediately. Use the event listeners to track status changes in real time. A payout moves funds from your Nylon Pay balance to an external mobile money wallet or bank account.

const payout = await nylonpay.makePayout(request);

Request Fields

Field	Type	Required	Description
`amount`	`number`	yes	Payout amount in smallest currency unit. Minimum 5000 UGX
`currency`	`Currency`	yes	ISO 4217 currency code (e.g., `"UGX"`)
`description`	`string`	yes	Payout description
`customer.name`	`string`	yes	Recipient full name
`customer.phoneNumber`	`string`	yes	Recipient phone number. Any common format accepted, auto-normalized to `256XXXXXXXXX`. See Phone Number Format
`customer.email`	`string`	no	Recipient email address
`destination.accountHolderName`	`string`	yes	Name on the receiving account
`destination.accountNumber`	`string`	yes	Mobile money number or bank account number
`destination.bankName`	`string`	no	Bank name, required for bank account payouts
`destination.phone`	`string`	no	Mobile money number when paying to a wallet. Any common format accepted, auto-normalized
`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

Example

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

const nylonpay = createNylonPay({
  apiKey: 'npk_test_...',
  apiSecret: 'nps_test_...',
});

const payout = await nylonpay.makePayout({
  amount: 50000,
  currency: 'UGX',
  description: 'Supplier payment #4471',
  customer: {
    name: 'Jane Doe',
    phoneNumber: '+256700000000',
  },
  destination: {
    accountHolderName: 'Jane Doe',
    accountNumber: '1234567890',
  },
  reference: '550e8400-e29b-41d4-a716-446655440000', // UUID (any version accepted)
});

payout.on('success', ({ transaction }) => {
  console.log('Payout delivered:', transaction.id);
});

Resolve Variant

Use makePayoutAndResolve() when you prefer a single blocking call instead of event listeners. It waits until the payout reaches a terminal state and returns a Result.

const result = await nylonpay.makePayoutAndResolve({
  amount: 50000,
  currency: 'UGX',
  description: 'Supplier payment #4471',
  customer: { name: 'Jane Doe', phoneNumber: '+256700000000' },
  destination: { accountHolderName: 'Jane Doe', accountNumber: '1234567890' },
});

if (result.isOk) {
  console.log('Payout status:', result.value.status);
}

Idempotency

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

Return Value

makePayout() 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

Make Payout