API reference
GET
/transactions/{reference}Read a transaction
Read a payment created by this application in this environment
Overview
Read the latest local state of a payment created by the authenticated application in the same environment. Another application’s or environment’s reference returns HTTP 404.
This endpoint does not initiate a provider query or send a second payment. Use it alongside signed webhooks to follow pending outcomes.
Example request
curl https://api.nuepay.net/v1/transactions/YOUR_REFERENCE \
-H "Authorization: Bearer $NUEPAY_TEST_KEY"Parameters
| Name | Location | Details |
|---|---|---|
reference | path | The NuePay payment reference returned at creation. |
Example response
{
"data": {
"reference": "NPTEXAMPLE01",
"project_id": "00000000-0000-4000-8000-000000000001",
"application_id": "00000000-0000-4000-8000-000000000001",
"application_name": "Online store",
"request_id": "00000000-0000-4000-8000-000000000002",
"idempotency_key": "00000000-0000-4000-8000-000000000002",
"merchant_reference": "order-123",
"type": "collection",
"status": "success",
"status_label": "Success",
"status_reason": null,
"refunded": false,
"amount": "500.00",
"fee": "20.00",
"gross_amount": "520.00",
"currency": "UGX",
"mode": "test",
"livemode": false,
"version": 1,
"payer_charge": "520.00",
"wallet_credit": "500.00",
"recipient_amount": null,
"wallet_debit": null
}
}Examples omit timestamps for readability. Use POST /quotes to confirm current fees rather than hard-coding these examples.
Response fields
| Field | Type | Details |
|---|---|---|
reference | string | See the response and related guide. |
project_id | string | See the response and related guide. |
application_id | string | See the response and related guide. |
application_name | string or null | See the response and related guide. |
request_id | string | See the response and related guide. |
idempotency_key | string | See the response and related guide. |
merchant_reference | string or null | See the response and related guide. |
status_reason | string or null | See the response and related guide. |
amount | string | See the response and related guide. |
fee | string | See the response and related guide. |
gross_amount | string | See the response and related guide. |
currency | string | See the response and related guide. |
payer_charge | string or null | See the response and related guide. |
wallet_credit | string or null | See the response and related guide. |
recipient_amount | string or null | See the response and related guide. |
wallet_debit | string or null | See the response and related guide. |
created_at | string | See the response and related guide. |
updated_at | string | See the response and related guide. |
type | string | collection, disbursement |
status | string | process, success, failed |
status_label | string | See the response and related guide. |
mode | string | live, test |
livemode | boolean | See the response and related guide. |
refunded | boolean | See the response and related guide. |
version | integer | See the response and related guide. |
HTTP status codes
| Status | Meaning |
|---|---|
200 | Current local payment state. |
201 | Invalid credentials. |
202 | Access unavailable or operation paused. |
203 | Resource not found in this application and environment. |
204 | Idempotency conflict, insufficient funds, or payout setup required. |
205 | Invalid input; inspect errors and code. |
206 | Rate limit exceeded. |
207 | Live provider unavailable; accepted payments can still be read or retried. |
Errors contain a stable code and support request_id. See error handling for recovery guidance.