# Integrate NuePay API v1

Build against https://api.nuepay.net/v1. Read the linked contract and relevant guides before writing code. If behavior is unspecified, flag the gap instead of inventing an endpoint or parameter.

## Implementation rules

- Call NuePay from your server with `Authorization: Bearer <secret>`. Keep credentials in environment variables; never embed them in browser code, prompts, logs or source control.
- A named key identifies its application and merchant. Do not send an application nickname or account number for authentication. Up to ten applications share the merchant wallet; there are no separate application wallets or spending scopes.
- Start with `np_test_` credentials and simulated funds. The same API base accepts test and live keys. Verify `/application` and the expected `mode` before testing. Only switch to real payments when explicitly authorized by the merchant.
- Send UGX amounts as decimal strings, never binary floating-point calculations. Collections credit the requested principal; the payer covers the quoted total, rounded up to whole UGX. Disbursements require whole UGX amounts and debit principal plus fee. Get `/quotes` before displaying charges; quotes do not move or reserve funds.
- Persist a UUID and the exact payment payload before calling `/collections` or `/disbursements`. Send that UUID in `Idempotency-Key`. After a timeout or retry, reuse both; never issue a fresh UUID to retry an uncertain payment. A changed payload with the same UUID returns `409`.
- `202` means accepted. The payment is complete only when `status` is `success`. `process` includes pending or under-review payments; a timeout is not proof of failure. Read `/transactions/{reference}` and reconcile before fulfilling or retrying.
- Handle non-2xx responses using `code`, `message` and `errors`. Log the HTTP `X-Request-Id` for investigation; `data.request_id` identifies the original payment UUID, not the current HTTP attempt. Honor rate limits and use bounded backoff.
- Configure each application's HTTPS notification URL in API Keys. Webhook and API signing secrets are separate. Verify `X-NuePay-Signature` using HMAC-SHA256 over `timestamp + "." + raw_body`, compare in constant time, and reject timestamps more than five minutes from your synchronized clock.
- After signature verification, match body `id` to `X-NuePay-Event-Id`, check `livemode`, durably deduplicate event IDs, and apply only newer payment `version` values. Save events before returning 2xx. Deliveries may repeat or arrive out of order; fulfil a real order only on a live success.

## Acceptance checks

- Test collection and disbursement success, failure and timeout with the sandbox simulation endpoint. Sandbox never moves real funds; sandbox webhook delivery is opt-in.
- Test identical retries, changed-payload conflicts and a network timeout after dispatch. Verify that neither charges nor fulfilment repeat.
- Test invalid signatures, stale timestamps, duplicate/out-of-order webhooks, test/live isolation and insufficient wallet funds.
- Store payment reference, application ID, merchant reference, idempotency UUID, status and version. Reconcile any unresolved payment before showing a final outcome.

## Read next

- [Quickstart](https://docs.nuepay.net/quickstart/index.md)
- [All endpoints](https://docs.nuepay.net/api/index.md)
- [Retries and statuses](https://docs.nuepay.net/reliability/index.md)
- [Webhook verification](https://docs.nuepay.net/webhooks/index.md)
- [Going live](https://docs.nuepay.net/going-live/index.md)

## Source

API v1. Behavior reviewed against platform commit `4133868d96070eef6352f9fe2a1d0278bcab38f6` on 2026-10-22.
Docs index: https://docs.nuepay.net/llms.txt. Contract: https://docs.nuepay.net/openapi.json.

---

# Build with AI

Give any coding agent the context to integrate NuePay.

Canonical page: https://docs.nuepay.net/agents/

## Give your agent context

Open the guide you need, choose your code language and select **Copy for AI**. Paste it into your coding tool with your task. It includes the guide, examples and the payment rules your integration needs.

```
Using the NuePay documentation below, implement server-side collections
in my existing application. Start in sandbox. Persist payment UUIDs,
handle retries and verify webhooks. Add tests for uncertain outcomes
and duplicate events. List any missing requirements before proceeding.
```

 

> **Keep secrets out of prompts.**
> 
> Use environment-variable placeholders. Review generated code and test payment flows before going live.

## Fetch only what you need

- [llms.txt](https://docs.nuepay.net/llms.txt) — a compact index for any agent.
- [Integration brief](https://docs.nuepay.net/integration.md) — payment rules and acceptance checks.
- [Markdown guides](https://docs.nuepay.net/quickstart/index.md) — the same content as these pages, without navigation.
- [OpenAPI](https://docs.nuepay.net/openapi.json) — all seven endpoints and webhook schemas.

Add `?language=python` to a Markdown URL for Python examples. Also available: `curl`, `php`, `javascript`, `typescript`, `go`, `java`, `csharp`, `ruby` and `rust`.

## Review before going live

Check credential storage, idempotent retries, signature verification and test/live isolation. Exercise success, failure, timeout and duplicate events in [sandbox](https://docs.nuepay.net/sandbox/index.md), then follow the [go-live checklist](https://docs.nuepay.net/going-live/index.md).