Nile Pay Docs

getStatus(request)

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

const result = await nile.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
Debugging: Check transaction state during development

Request

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

Response

interface StatusResponse {
  transactionId: string;
  reference: string;
  status: TransactionStatus;
  amount: number;
  currency: string;
  providerReference?: string;
  createdAt: string;
  updatedAt: string;
}

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

Result Pattern

All SDK methods return the Result pattern from slang-ts:

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

if (result.status) {
  const { status, amount, transactionId } = result.data;
  console.log(`${transactionId}: ${status} (${amount} ${currency})`);
} else {
  console.error("Failed to get status:", result.message);
}

Example

import { createNilePay } from "@nilepay/sdk";

const nile = createNilePay({
  environment: "sandbox",
  apiKey: "npk_test_...",
  apiSecret: "nps_test_...",
});

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

  if (!result.status) {
    return { valid: false, reason: result.message };
  }

  const tx = result.data;

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

Webhook Verification

Use getStatus() in your webhook handler to verify the payment before fulfillment:

app.post("/webhooks/nilepay", async (req, res) => {
  const { reference, status } = req.body;

  // Verify with Nile Pay API
  const result = await nile.getStatus({ reference });

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

  // Fulfill order
  await fulfillOrder(result.data.metadata.orderId);

  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

Get Status