API Reference · Payins

Query payin status

Look up the current status of one of your payins by its reference. Sign it with HMAC-SHA256 the same way as Create a payin, with GET as the method, /payment/api/payins/status (without the query string) as the path, and reference=<your reference> as the canonical body. X-Merchant-ID is required, and unsigned requests are refused. It answers only for the environment in X-Tenant-ID, where a missing or mistyped header means test, so a live pay-in reads NOT_FOUND under test and the other way round. status is PENDING (statusCode 0), SUCCESS (2), FAILED (3), TIMED_OUT (8) or UNKNOWN (9). TIMED_OUT means no provider verdict arrived within 10 minutes of creation: it is not a provider result, and the pay-in is not checked again.

GEThttps://payment.klustar.io/payment/api/payins/status

Query params

reference

stringrequired

The reference used when creating the payin. Signed as the canonical body reference=<value>, unencoded.

Headers

X-Tenant-ID

stringrequired

The environment of this call: test or live, ignoring case and surrounding spaces. It is not an account identifier, nothing issues it, and it is not signed. On Create a payin and Query payin status a missing or mistyped value means test, with no error. Account enquiry and Query payout status refuse a missing value and treat a mistyped one as test. live needs approval: until then a correctly signed live request gets 403 LIVE_NOT_ENABLED.

X-API-KEY

stringrequired

Public API key from the merchant dashboard. The same key serves test and live.

X-Merchant-ID

stringrequired

Your App ID, shown beside your API key on Profile & Settings → API Keys.

X-Nonce

stringrequired

A new value on every request (UUID recommended), including a retry after a failure. A nonce is recorded before the signature is checked and stays used, so a refused request burns it.

X-Timestamp

stringrequired

Unix epoch seconds when the request is signed, digits only. Must be within ±300s of server time.

X-Signature

stringrequired

Lowercase hex HMAC-SHA256 of the signature base string, using your secret key.

Responses

klustarReference is always null, and gatewayReference is null on Korapay pay-ins: use your own reference. merchant reads "Merchant <App ID>" for a business that generated its keys before approval, until it is approved for live. Webhooks say successful and failed where this says SUCCESS, FAILED and TIMED_OUT.

Response body

{
  "statusCode": 2,
  "status": "SUCCESS",
  "message": "Transaction status retrieved",
  "reference": "ORDER-8f14e45f-ceea-467d-a5b3-0c1f7b2d9e11",
  "klustarReference": null,
  "gatewayReference": null,
  "gateway": "KORAPAY",
  "amount": 2000.00,
  "currency": "NGN",
  "paymentMethod": "CARD",
  "merchantId": "00000000-0000-4000-8000-000000000001",
  "merchant": "Your business name",
  "timestamp": "2026-10-31T10:32:15.123",
  "transactionDate": "2026-10-31T09:32:15.123Z"
}

{
  "statusCode": 2,
  "status": "SUCCESS",
  "message": "Transaction status retrieved",
  "reference": "ORDER-8f14e45f-ceea-467d-a5b3-0c1f7b2d9e11",
  "klustarReference": null,
  "gatewayReference": null,
  "gateway": "KORAPAY",
  "amount": 2000.00,
  "currency": "NGN",
  "paymentMethod": "CARD",
  "merchantId": "00000000-0000-4000-8000-000000000001",
  "merchant": "Your business name",
  "timestamp": "2026-10-31T10:32:15.123",
  "transactionDate": "2026-10-31T09:32:15.123Z"
}