/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"
<?php
$curl = curl_init('https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001');
curl_setopt_array($curl, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('NUEPAY_TEST_KEY'),
],
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false || $status >= 400) {
throw new RuntimeException('Request failed; check its status before retrying.');
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
curl_close($curl);
print_r($result);
const response = await fetch('https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001', {
method: 'GET',
headers: {
Authorization: 'Bearer ' + process.env.NUEPAY_TEST_KEY,
},
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error('HTTP ' + response.status);
console.log(await response.json());
const response: Response = await fetch('https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001', {
method: 'GET',
headers: {
Authorization: 'Bearer ' + process.env.NUEPAY_TEST_KEY!,
},
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error('HTTP ' + response.status);
console.log(await response.json());
import json, os, urllib.request
request = urllib.request.Request(
'https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001',
method='GET',
headers={
'Authorization': 'Bearer ' + os.environ['NUEPAY_TEST_KEY'],
},
)
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
print(result)
package main
import (
"fmt"
"io"
"net/http"
"os"
"time"
)
func main() {
request, err := http.NewRequest("GET", "https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001", nil)
if err != nil { panic(err) }
request.Header.Set("Authorization", "Bearer " + os.Getenv("NUEPAY_TEST_KEY"))
client := &http.Client{Timeout: 30 * time.Second}
response, err := client.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
if err != nil { panic(err) }
if response.StatusCode >= 400 { panic(response.Status) }
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
public class NuePayExample {
public static void main(String[] args) throws Exception {
var client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(5)).build();
var request = HttpRequest.newBuilder(URI.create("https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001"))
.timeout(Duration.ofSeconds(30))
.header("Authorization", "Bearer " + System.getenv("NUEPAY_TEST_KEY"))
.method("GET", HttpRequest.BodyPublishers.noBody()).build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) {
throw new RuntimeException("HTTP " + response.statusCode());
}
System.out.println(response.body());
}
}
using System;
using System.Net.Http;
using System.Text;
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001");
request.Headers.Add("Authorization",
"Bearer " + Environment.GetEnvironmentVariable("NUEPAY_TEST_KEY"));
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
require 'net/http'
require 'json'
uri = URI('https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer ' + ENV.fetch('NUEPAY_TEST_KEY')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.open_timeout = 5
http.read_timeout = 30
response = http.request(request)
raise "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts JSON.parse(response.body)
// cargo add reqwest --features blocking
use std::{env, error::Error, time::Duration};
fn main() -> Result<(), Box<dyn Error>> {
let client = reqwest::blocking::Client::builder()
.timeout(Duration::from_secs(30)).build()?;
let response = client.get("https://api.nuepay.net/v1/collections/00000000-0000-4000-8000-000000000001")
.bearer_auth(env::var("NUEPAY_TEST_KEY")?)
.send()?.error_for_status()?.text()?;
println!("{}", response);
Ok(())
}
Parameters
| Name | Location | Details |
|---|---|---|
requestId | path | The 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
| Field | Type | Details |
|---|---|---|
referencerequired | string | NuePay payment reference. Use it to read this payment. |
project_idrequired | string · uuid or null | Application ID; retained alongside application_id in the payment resource. |
application_idrequired | string · uuid or null | The application identified by the secret used to create this payment. |
application_namerequired | string or null | Application nickname recorded for this payment. It is not an authentication parameter. |
request_idrequired | string · uuid or null | Original payment idempotency UUID, not the current HTTP X-Request-Id. |
idempotency_keyrequired | string · uuid or null | The original Idempotency-Key UUID. |
merchant_referencerequired | string or null | Your optional order reference. It does not provide idempotency. |
status_reasonrequired | string or null | Additional reason, including payment_timeout when an unconfirmed collection reaches its two-minute deadline, awaiting_confirmation or review_required; null when absent. |
amountrequired | string | Requested principal, as a UGX decimal string. |
feerequired | string | Quoted fee, as a UGX decimal string. |
gross_amountrequired | string | Principal plus fee, as a UGX decimal string. |
currencyrequired | string | — |
payer_chargerequired | string or null | Total charged to the collection payer; null for disbursements. |
wallet_creditrequired | string or null | Collection principal credited to the wallet; null for disbursements. |
recipient_amountrequired | string or null | Amount sent to the disbursement recipient; null for collections. |
wallet_debitrequired | string or null | Disbursement principal plus fee; null for collections. |
created_atrequired | string · date-time or null | Creation timestamp in ISO 8601 format. |
updated_atrequired | string · date-time or null | Last update timestamp in ISO 8601 format. |
expires_atrequired | string · date-time or null | Collection confirmation deadline in ISO 8601, 120 seconds after created_at; null for disbursements. |
typerequired | string | collection, disbursement |
statusrequired | string | process is unresolved; only success confirms payment. Unconfirmed collections become failed after 120 seconds. An HTTP timeout alone does not establish the outcome. |
status_labelrequired | string | Display label. Use status for program logic. |
moderequired | string | test uses simulated funds; live uses real funds. |
livemoderequired | boolean | True only for real payments. Check it before fulfilling a live order. |
refundedrequired | boolean | Whether a failed disbursement has been refunded to the wallet. |
versionrequired | integer | Monotonically increasing payment state version. Ignore older webhook versions. |
HTTP status codes
| Status | Meaning |
|---|---|
200 | Current collection state. |
401 | Invalid credentials. |
403 | Access unavailable or operation paused. |
404 | Resource not found in this application and environment. |
409 | Idempotency conflict, quote changed, insufficient funds, or payout setup required. |
422 | Invalid input; inspect errors and code. |
429 | Rate limit exceeded. |
503 | Live provider unavailable; accepted payments can still be read or retried. |

