---
name: nopan-testing
description: Apply this guide when testing a Nopan integration against the sandbox — driving deterministic outcomes with mocks, using Pass-Through mocking against real scheme sandboxes, importing and running the Postman collection, or writing integration tests for payment flows. Relevant for any pre-production validation work, including CI checks and the go-live readiness checklist.
---

# Nopan testing

Nopan ships sandbox tooling so you can validate signing, payloads, error handling, and full lifecycle flows without touching real money or real schemes.

> Authoritative pages: [Mocking](https://docs.nopan.com/guides/mocking), [Integration Walkthrough](https://docs.nopan.com/guides/integration-walkthrough), and the OpenAPI [`/api`](https://docs.nopan.com/api) for `/mock/set` and `/mock/payment/{transactionId}/approve`.

> **Match existing patterns** — follow the project's existing test conventions for other payment-provider integrations: fixture layout, mock vs integration vs contract-test split, naming, CI gating, and test-double strategy. Nopan tests should live alongside the existing payment-provider tests using the same shape, not in a separate suite. The Standard Mock vs Pass-Through choice below maps onto the *unit vs end-to-end* split the project likely already has. See [`nopan-integration`](https://docs.nopan.com/skills/nopan-integration.md) Step 0.

## Where mocking runs

Mocking is **sandbox-only**. The base URL is `https://api.sandbox.nopan.dev`. Production (`https://api.nopan.io`) ignores mock configuration and always routes to real schemes.

## Two mocking modes

Pick the mode by the question you're trying to answer.

### Standard Mock

- **No real scheme is involved.** Nopan simulates the provider response based on what you configure.
- You fully control the outcome (success, failure, timeout, decline reason, etc.).
- No redirects, no third-party UI. Fast and deterministic.
- **Use when:** writing backend tests, exercising error paths, or running in CI.

### Pass-Through mocking

- The request **is** routed through the real scheme's sandbox.
- You declare the outcome you want; Nopan handles the scheme-specific tricks (redirect URLs, test codes, parameters) to drive that outcome.
- Real flow is preserved — redirects and third-party UIs happen.
- **Use when:** doing end-to-end / manual / UX testing where you want the genuine scheme behavior.

### Choosing between them

| Question | Mode |
|---|---|
| "Does my backend handle a `4xxx` validation error correctly?" | Standard Mock |
| "Does my checkout redirect handling work against BLIK's real sandbox?" | Pass-Through |
| "Can I run this in CI every commit?" | Standard Mock |
| "Does the SCA redirect from this scheme actually return the shopper to my page?" | Pass-Through |
| "Do I want to override response field values for a specific test case?" | Standard Mock (Pass-Through doesn't allow overrides) |

## How mocks are configured

Two endpoints in the sandbox-only API:

- `POST /mock/set` — register an outcome for a future payment (typically keyed on `clientTransactionId` or another identifier). Use **before** the payment is initiated.
- `POST /mock/payment/{transactionId}/approve` — explicit approval for flows that wait on shopper action.

The exact request/response shapes are in the OpenAPI under the `Mocking APIs` tag — fetch them from [https://docs.nopan.com/api](https://docs.nopan.com/api) when implementing.

> Default sandbox behavior when no mock is set: the request flows to the real scheme without modification.

## Postman collection

A pre-built Postman collection ships at [`/postman/nopan-api-collection.zip`](https://docs.nopan.com/postman/nopan-api-collection.zip).

What it gives you out of the box:

- All endpoints organized by OpenAPI tag.
- **Automatic** mTLS, request signing (RFC-9421, algorithm auto-detected from key type), and Bearer token injection — you don't hand-roll these in pre-request scripts.
- Pre-configured `/auth/token` body and token extraction.

Setup steps (the import wizard guides you, but the prerequisites are):

1. Add your client certificate and private key in Postman Settings → Certificates for the API domain.
2. Set the collection variables:
   - `base_url` (defaults to sandbox)
   - `organization_id`
   - `processing_account_id`
   - `signing_key_id`
   - `signing_private_key` (PKCS#8 PEM, full text including headers)
3. Run `/auth/token` first — `access_token` is auto-populated.
4. Make any other request — everything is signed and bearer-auth'd automatically.

Common pitfalls: missing or non-PKCS#8 private key, certificate not added in Postman settings, expired token left in the variable.

## Recommended sandbox test plan

Before go-live, exercise at minimum:

1. **Auth surface**
   - `/auth/token` happy path.
   - `/auth/token` with expired cert → expect `400 / 4980` (or similar).
   - Business endpoint with expired token → expect `401 / 4061`.
   - Business endpoint with tampered signature → expect `401 / 4051` (or similar signature reason).
2. **Payments — happy paths**
   - CIT: `initiate` → `finalize` (with `autoCapture=true` and `false`).
   - MIT: `charge`.
   - Optional separate `capture`, `refund`, `cancel`.
3. **Payments — unhappy paths** (use Standard Mock to drive these)
   - Scheme decline.
   - Insufficient funds (`1xxx`).
   - Shopper cancel (`2xxx`).
   - Idempotency conflict — replay key with different payload, expect `409 / 3xxx`.
4. **Webhooks**
   - Endpoint receives the events you subscribed to.
   - Signature verification accepts valid, rejects tampered.
   - Retry behavior on a deliberate non-2xx response.
5. **Reports**
   - Token scoped with `data:reports` retrieves `/reports`.
   - `/reports/download` returns the expected file.

For the full Go-Live checklist, see [Integration Walkthrough](https://docs.nopan.com/guides/integration-walkthrough#go-live-checklist).

## Decision rules

- **Writing automated tests** → Standard Mock + a fresh idempotency key per test.
- **Manually validating a checkout** → Pass-Through against the scheme sandbox.
- **Got "no mock set" behavior unexpectedly** → confirm `/mock/set` was called for that `clientTransactionId` **before** initiating the payment.
- **Want to test webhook flows without a real shopper** → drive outcomes with Standard Mock; Nopan still emits the matching webhook events.
- **Trying to reproduce a prod bug** → reproduce in sandbox first using Standard Mock; if scheme behavior matters, switch to Pass-Through.

## Related guides

- Setting up the credentials Postman needs → [`nopan-authentication`](https://docs.nopan.com/skills/nopan-authentication.md).
- Picking which payment endpoint to exercise → [`nopan-payments`](https://docs.nopan.com/skills/nopan-payments.md).
- Validating webhook delivery → [`nopan-webhooks`](https://docs.nopan.com/skills/nopan-webhooks.md).
- Interpreting expected error responses → [`nopan-errors`](https://docs.nopan.com/skills/nopan-errors.md).