API reference
POST/sandbox/transactions/{reference}/simulate

Simulate 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

Simulate a test outcome
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

NameLocationDetails
referencepathThe NuePay payment reference returned at creation.

Request body

FieldTypeDetails
outcomerequiredstringsuccess, failed, timeout

Example response

Illustrative sandbox 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

FieldTypeDetails
referencestringSee the response and related guide.
project_idstringSee the response and related guide.
application_idstringSee the response and related guide.
application_namestring or nullSee the response and related guide.
request_idstringSee the response and related guide.
idempotency_keystringSee the response and related guide.
merchant_referencestring or nullSee the response and related guide.
status_reasonstring or nullSee the response and related guide.
amountstringSee the response and related guide.
feestringSee the response and related guide.
gross_amountstringSee the response and related guide.
currencystringSee the response and related guide.
payer_chargestring or nullSee the response and related guide.
wallet_creditstring or nullSee the response and related guide.
recipient_amountstring or nullSee the response and related guide.
wallet_debitstring or nullSee the response and related guide.
created_atstringSee the response and related guide.
updated_atstringSee the response and related guide.
typestringcollection, disbursement
statusstringprocess, success, failed
status_labelstringSee the response and related guide.
modestringlive, test
livemodebooleanSee the response and related guide.
refundedbooleanSee the response and related guide.
versionintegerSee the response and related guide.

HTTP status codes

StatusMeaning
200Simulated result.
201Invalid credentials.
202Access unavailable or operation paused.
203Resource not found in this application and environment.
204Idempotency conflict, insufficient funds, or payout setup required.
205Invalid input; inspect errors and code.
206Rate limit exceeded.
207Live 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.

Made for builders. Built in Uganda.NuePay API v1

Search endpoints, guides and examples.