GET/collections/{requestId}

Recover a collection

Find an accepted collection using its saved request UUID.

Lost the collection response? Use the UUID you saved in Idempotency-Key. This lookup never sends a phone prompt.

Request

Replace the example UUID with your original payment UUID. Use the same application's secret and environment.

curl -X GET https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $NUEPAY_TEST_KEY"

Parameters

NameLocationDetails
requestIdpathThe original UUID supplied in Idempotency-Key when creating the collection.

Use the result

200: the same payment resource as transaction status. Only success confirms payment. 404: no accepted collection matches this application, environment and UUID; no payment is created by this lookup.

Set request_expires_at when creating the collection to prevent an old request arriving after your checkout deadline. Keep that value unchanged on retries. Once that deadline has passed, a 404 confirms that request can no longer create a collection. Disbursements are excluded.

All response fields
FieldTypeDetails
referencerequiredstringNuePay payment reference. Use it to read this payment.
project_idrequiredstring · uuid or nullApplication ID; retained alongside application_id in the payment resource.
application_idrequiredstring · uuid or nullThe application identified by the secret used to create this payment.
application_namerequiredstring or nullApplication nickname recorded for this payment. It is not an authentication parameter.
request_idrequiredstring · uuid or nullOriginal payment idempotency UUID, not the current HTTP X-Request-Id.
idempotency_keyrequiredstring · uuid or nullThe original Idempotency-Key UUID.
merchant_referencerequiredstring or nullYour optional order reference. It does not provide idempotency.
status_reasonrequiredstring or nullAdditional reason, including payment_timeout when an unconfirmed collection reaches its two-minute deadline, awaiting_confirmation or review_required; null when absent.
amountrequiredstringRequested principal, as a UGX decimal string.
feerequiredstringQuoted fee, as a UGX decimal string.
gross_amountrequiredstringPrincipal plus fee, as a UGX decimal string.
currencyrequiredstring—
payer_chargerequiredstring or nullTotal charged to the collection payer; null for disbursements.
wallet_creditrequiredstring or nullCollection principal credited to the wallet; null for disbursements.
recipient_amountrequiredstring or nullAmount sent to the disbursement recipient; null for collections.
wallet_debitrequiredstring or nullDisbursement principal plus fee; null for collections.
created_atrequiredstring · date-time or nullCreation timestamp in ISO 8601 format.
updated_atrequiredstring · date-time or nullLast update timestamp in ISO 8601 format.
expires_atrequiredstring · date-time or nullCollection confirmation deadline in ISO 8601, 120 seconds after created_at; null for disbursements.
typerequiredstringcollection, disbursement
statusrequiredstringprocess is unresolved; only success confirms payment. Unconfirmed collections become failed after 120 seconds. An HTTP timeout alone does not establish the outcome.
status_labelrequiredstringDisplay label. Use status for program logic.
moderequiredstringtest uses simulated funds; live uses real funds.
livemoderequiredbooleanTrue only for real payments. Check it before fulfilling a live order.
refundedrequiredbooleanWhether a failed disbursement has been refunded to the wallet.
versionrequiredintegerMonotonically increasing payment state version. Ignore older webhook versions.
HTTP status codes
StatusMeaning
200Current collection state.
401Invalid credentials.
403Access unavailable or operation paused.
404Resource not found in this application and environment.
409Idempotency conflict, quote changed, insufficient funds, or payout setup required.
422Invalid input; inspect errors and code.
429Rate limit exceeded.
503Live provider unavailable; accepted payments can still be read or retried.

Error codes and recovery →

NuePayAPI v1

Search endpoints, guides and examples.