Check a transaction

Check-transaction answers one question: what happened to the ledger debit behind a reference you hold, on your own account or on an agent’s you debited. Call it when a money-moving request timed out before you read the reply, when you were told 0009, or before you retry anything.

POST/api/legacy/provider/wallets/transactions/checktranscope: transactions:read

Request

Field	Type	Required	Description
transactionRef	string	Yes	Either the transactionRef you supplied on the original call, or the retRef BankCore returned.

The lookup tries your reference first, then BankCore’s. Where several transactions share your reference (an interbank transfer’s principal plus its fee, VAT and stamp duty lines), the principal leg is the one answered for.

cURL

curl -X POST https://api.bankcore.ng/api/legacy/provider/wallets/transactions/checktran \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transactionRef": "SAL-20260401-001" }'

Request body

{ "transactionRef": "SAL-20260401-001" }

Response

{
  "code": "0000",
  "desc": "COMPLETED",
  "retRef": "TRF20260401143000A1B2",
  "clientRef": "SAL-20260401-001",
  "fromAccount": "6020000001",
  "toAccount": "6020012345",
  "transdatetime": "20260401143000"
}

Field	Description
code	Derived from the transaction’s status; see the table below.
desc	The status name: COMPLETED, PENDING, HELD, FAILED or REVERSED.
retRef	BankCore’s reference.
clientRef	The reference stored against the transaction. For a transaction you created, your transactionRef.
fromAccount, toAccount	Whichever sides the transaction has. A one-sided debit (a bill payment, an interbank principal) has no toAccount.
transdatetime	When it was posted, or created if not yet posted. yyyyMMddHHmmss.

Status semantics

Code	Status	Meaning
0000	COMPLETED	Posted. The balance moved.
0009	PENDING, HELD	In flight. Money may have moved or been held: a high-value transfer awaiting the bank’s approval, for instance. Do not resend.
0096	FAILED, REVERSED	Terminal. Funds were restored where they had been taken. A retry needs a new reference, because the old one stays reserved.
0012	—	No transaction carries that reference. If you sent the original request and never got a reply, the request did not reach posting; resend it with the same reference.

What this endpoint does not tell you

It reports the ledger debit, not the outcome of anything that happened after it. An interbank transfer’s debit is COMPLETED the moment the customer is debited, while NIBSS may still be processing it; a bill payment’s debit is COMPLETED before the biller has answered. For those, use the status in the original reply, the nip.transfer.* and bill.payment.* webhooks, and the portal. A reversal shows up as a separate REVERSAL line on the statement, not as a change to this answer. See Interbank transfer and Bills and airtime.

Polling guidance for 0009

1. Keep the original reference. It is the only key you need.
2. Poll every 5 seconds for the first minute, then every 30 seconds. There is no benefit in polling faster; the state changes when the bank acts, not when you ask.
3. Stop on 0000 or 0096. A high-value approval can take as long as a bank officer takes; after a few hours, raise it with your relationship manager rather than continuing to poll.
4. Never re-submit the payment while the answer is 0009. Re-submitting with the same reference is refused with 0094; re-submitting with a new one pays twice.

Agent twin

POST/api/legacy/agent/transact/checktranscope: transactions:read

Same body. Two differences: it looks up BankCore’s reference only (the retRef), not your own, and it always answers 0000 with the status in desc when found, 0012 when not. The X-Agent-Account header is not read by this call.

{ "code": "0000", "desc": "COMPLETED" }

Prefer the customer endpoint even for agent transactions: it accepts your reference and maps the status into the code.

In the portal

The Transactions register shows every posting with its status, and the Interbank transfers page shows where a NIP payment actually is.