API reference
POST
/collectionsCreate a collection
Collect mobile money into the wallet
Overview
Collect mobile money from an MTN or Airtel phone into the merchant wallet. The amount is the wallet principal; the payer approves the amount plus fee. The call is asynchronous.
Only a confirmed success credits the wallet. While a payment is pending or under review, do not fulfil the order. Live processing requires an eligible account and available provider integration.
Example request
curl https://api.nuepay.net/v1/collections \
-H "Authorization: Bearer $NUEPAY_TEST_KEY" \
-H "Idempotency-Key: $PAYMENT_UUID" \
-H 'Content-Type: application/json' \
-d '{
"amount": "500.00",
"currency": "UGX",
"phone": "0772000000",
"merchant_reference": "order-123"
}'// Persist this UUID with your order; reuse it when retrying.
const response = await fetch('https://api.nuepay.net/v1/collections', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NUEPAY_TEST_KEY}`,
'Idempotency-Key': paymentUuid,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '500.00', currency: 'UGX',
phone: '0772000000', merchant_reference: 'order-123',
}),
});
const result = await response.json();
if (!response.ok) throw new Error(result.message);
console.log(result.data);$curl = curl_init('https://api.nuepay.net/v1/collections');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('NUEPAY_TEST_KEY'),
'Idempotency-Key: '.$paymentUuid, // Reuse for retries.
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => '500.00', 'currency' => 'UGX',
'phone' => '0772000000', 'merchant_reference' => 'order-123',
]),
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false || $status < 200 || $status >= 300) {
throw new RuntimeException('Inspect the error and retry safely.');
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);import json, os, urllib.request
request = urllib.request.Request(
'https://api.nuepay.net/v1/collections',
method='POST',
headers={
'Authorization': 'Bearer ' + os.environ['NUEPAY_TEST_KEY'],
'Idempotency-Key': payment_uuid, # Reuse for retries.
'Content-Type': 'application/json',
},
data=json.dumps({
'amount': '500.00', 'currency': 'UGX',
'phone': '0772000000', 'merchant_reference': 'order-123',
}).encode(),
)
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
print(result['data'])Parameters
| Name | Location | Details |
|---|---|---|
Idempotency-Key | header | Keep the same UUID when retrying the same payment. Legacy X-NuePay-Request-Id is accepted. |
Request body
| Field | Type | Details |
|---|---|---|
amountrequired | string | Wallet principal for collections; recipient amount for disbursements. |
currencyrequired | string | UGX |
phonerequired | string | Uganda MTN or Airtel number; local or +256 format. |
merchant_reference | string | See the response and related guide. |
description | string | See the response and related guide. |
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": "process",
"status_label": "Pending",
"status_reason": null,
"refunded": false,
"amount": "500.00",
"fee": "20.00",
"gross_amount": "520.00",
"currency": "UGX",
"mode": "test",
"livemode": false,
"version": 0,
"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 | Existing payment returned for an identical retry. |
202 | Accepted for processing. |
203 | Invalid credentials. |
204 | Access unavailable or operation paused. |
205 | Resource not found in this application and environment. |
206 | Idempotency conflict, insufficient funds, or payout setup required. |
207 | Invalid input; inspect errors and code. |
208 | Rate limit exceeded. |
209 | 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.

