Nylon Pay Docs

getStatus(request)

Retrieves the current status of a transaction. Returns a Result object.

const result = await nylonpay.getStatus({ reference });

When to Use

Webhook verification: Confirm payment status before fulfilling orders
Your own dashboards: Display payment status to customers or operators
Fallback: Verify status if the event-driven flow fails or times out

Request

type GetStatusInput = {
  reference: string; // the reference used in collectPayment()
};

Response

type StatusResponse = {
  reference: string;
  status: TransactionStatus;
  amount: number;
  currency: Currency;
  id: string;
  operatorTid: string | null;
  failureReason: string | null;
  failureCategory?: FailureCategory | null;
  failureCode?: FailureCode | null;
  statusText?: string;
  delayed?: boolean;
  updatedAt: string;
};

Field	Description
`id`	Nylon transaction ID
`operatorTid`	ID on the customer's operator or bank receipt. `null` until it is reported
`failureReason`	Human sentence when the payment failed or was cancelled, otherwise `null`
`failureCategory`	Broad class: `provider`, `customer`, `internal`, `validation`
`failureCode`	Nylon code such as `insufficient_balance`
`statusText`	Extra human sentence. For `on_hold`, why the payout is in review
`delayed`	`true` when the payment has been waiting longer than a few minutes

type TransactionStatus =
  | 'pending'
  | 'processing'
  | 'on_hold'
  | 'successful'
  | 'failed'
  | 'cancelled';

Result Pattern

All SDK methods return the Result pattern. Always check result.isOk before accessing data.

const result = await nylonpay.getStatus({ reference });

if (result.isOk) {
  const { reference, status, amount, currency } = result.value;
  console.log(`${reference}: ${status} (${amount} ${currency})`);
} else {
  console.error('Failed to get status:', result.error);
}

Example

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

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

async function verifyPayment(reference: string) {
  const result = await nylonpay.getStatus({ reference });

  if (result.isErr) {
    return { valid: false, reason: result.error };
  }

  const tx = result.value;

  return {
    valid: tx.status === 'successful',
    reason:
      tx.status === 'successful' ? 'Payment confirmed' : `Payment ${tx.status}`,
    transaction: tx,
  };
}

Webhook Verification

Always verify webhook payloads with getStatus() before fulfilling orders. The transaction reference lives inside the payload object of the webhook body:

app.post('/webhooks/nylonpay', async (req, res) => {
  const { reference } = req.body.payload;

  const result = await nylonpay.getStatus({ reference });

  if (result.isErr || result.value.status !== 'successful') {
    return res.status(400).json({ error: 'Invalid payment' });
  }

  res.status(200).json({ received: true });
});

vs Event-Driven Approach

Aspect	`getStatus()`	Event-Driven (`on`/`wait`)
Control	Pull model	Push model
Latency	On-demand	Real-time
Use case	Verification, admin	User-facing flows
Complexity	Simpler	Event-driven

When to Use Which

Scenario	Recommended
You need to confirm a payment after a timeout	`getStatus()`
You're building an admin dashboard	`getStatus()`
Your webhook received a notification	Both, use webhook plus verify with `getStatus()`
You need real-time UI updates during payment	Event-driven (`on`/`wait`)
You're writing a simple script	Event-driven (`wait()`)

getTransaction(input)

Retrieves the full transaction record. Requires at least one of id or reference.

const result = await nylonpay.getTransaction({ reference });

if (result.isOk) {
  const tx = result.value;
  console.log(tx.id, tx.status, tx.amount);
}

Field	Type	Required	Description
`id`	`string`	no	Transaction ID. Either `id` or `reference` required
`reference`	`string`	no	The reference used at creation. Either `id` or `reference` required

Unlike getStatus(), which returns a lightweight summary, getTransaction() returns the complete transaction record (customer, method, tags, timestamps, and more).

verifyPhone(input)

Confirms a phone number and returns the registered name. Use it to verify customer identity before you initiate a collection or payout.

const result = await nylonpay.verifyPhone({ phoneNumber: '+256700000000' });

if (result.isOk) {
  console.log(result.value.customerName); // confirmed account name
}

Field	Type	Required	Description
`phoneNumber`	`string`	yes	Phone number in any common format, auto-normalized
`purpose`	`"collection"` or `"payout"`	no	Whether you plan to collect or disburse

Returns { phoneNumber, customerName, verified }. When verification succeeds, customerName holds the registered name and verified is true; when the number can't be matched, verified is false.

Get Status