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
Admin dashboards: Display payment status to merchants
Fallback: Verify status if event-driven flow fails or times out
Debugging: Check transaction state during development

Request

interface GetStatusRequest {
  reference: string; // the reference used in collectPayment()
}

Response

interface StatusResponse {
  reference: string;
  status: TransactionStatus;
  amount: number;
  currency: string;
  updatedAt: string;
  operatorTid?: string | null;
}

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

Result Pattern

All SDK methods return the Result patter. Always checkout status 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 oreders:

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

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

Get Status