Verify a payment

Call GET /payments/:reference from your backend after a payer returns and when reconciling a webhook. Use a secret key from the same environment that created the payment; a Live key cannot read a Sandbox transaction.

const response = await fetch(
  `https://api.skypay.ng/api/v1/payments/${encodeURIComponent(reference)}`,
  { headers: { Authorization: `Bearer ${process.env.SKYPAY_SECRET_KEY}` } }
)
const result = await response.json()

if (!response.ok) throw new Error(result.error?.message ?? 'Lookup failed')
if (result.data.amount !== order.amountKobo) throw new Error('Amount mismatch')
if (result.data.currency !== 'NGN') throw new Error('Currency mismatch')
if (result.data.status === 'SUCCESS') await fulfilOrderOnce(order.id)

Response fields

Field	Meaning
`reference`	Public SkyPay transaction reference
`amount`	Integer kobo
`currency`	Transaction currency
`status`	Current normalized status
`gateway`	Processor slug, if assigned
`customerEmail`, `customerName`	Optional payer details
`environment`	`SANDBOX` or `LIVE`
`initiatedAt`, `completedAt`	ISO timestamps
`failureReason`	Safe reason for a failed payment, if available
`metadata`	Merchant-provided metadata

Statuses

Status	Meaning	Action
`INITIATED`	Payment reference exists; processing has not begun	Wait or let the payer open checkout
`PENDING`	Processor or payer action is in progress	Keep the order pending and check later
`SUCCESS`	Payment is confirmed	Validate amount/currency and fulfil once
`FAILED`	Payment failed	Show a safe retry path
`REVERSED`	A previously successful payment was reversed	Reconcile and follow your reversal policy

The browser callback is navigation, not proof of payment. Query parameters can be forged. Your server must use this endpoint or a verified webhook before delivering value.

Response fields​

Statuses​

Response fields

Statuses