API reference
POST
/sandbox/transactions/{reference}/simulateSimulate a test outcome
Simulate an outcome using a test key
Overview
Resolve a sandbox payment as successful, failed or uncertain. This operation accepts only np_test_ keys and the owning application’s test references.
A timeout stays pending with awaiting_confirmation; it can later succeed or fail. Repeating the same final result does not repeat credits or refunds. A contradictory final outcome returns a conflict.
Example request
curl -X POST https://api.nuepay.net/v1/sandbox/transactions/YOUR_REFERENCE/simulate \
-H "Authorization: Bearer $NUEPAY_TEST_KEY" \
-H 'Content-Type: application/json' \
-d '{"outcome":"success"}'Parameters
| Name | Location | Details |
|---|---|---|
reference | path | The NuePay payment reference returned at creation. |
Request body
| Field | Type | Details |
|---|---|---|
outcomerequired | string | success, failed, timeout |
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 | Simulated result. |
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.

