---
name: nopan-integration
description: Apply this guide when starting or planning an integration with Nopan — the merchant-native payments platform for account-to-account (A2A) and digital wallet payments. Relevant whenever the user is integrating with Nopan, calling its API, or setting up a sandbox or production environment. This is the entry-point guide — it instructs the agent to first inspect how the project already integrates other payment providers, then orients on environments, authentication layers, and which topic guide to load next.
---

# Nopan integration overview

Nopan is a payments API focused on account-to-account (A2A) and digital wallet payments (BLIK, Bizum, Iris, Satispay, Wero, and more). This guide is the orientation layer — use it to map the user's task to the right topic guide and the right doc page.

> **Source of truth:** [https://docs.nopan.com](https://docs.nopan.com). Always fetch the linked page when you need current detail (payloads, schemas, examples).

## Step 0 — Match the project's existing payment integrations

**Do this before writing any Nopan code.** Nopan should slot into the patterns the codebase already uses for other providers — not stand on its own with the canonical examples from these guides. The topic guides below describe Nopan's mechanics; the *shape* of the code you write should come from this step.

### Discovery checklist

1. **Find prior providers.** Look for payment-provider SDK imports in `package.json` / `pom.xml` / `requirements.txt` / `go.mod`, provider-named folders under `payments/`, `gateways/`, or `providers/`, and webhook routes under `/webhooks/*`. Treat any third-party payments SDK already wired up as a prior integration.
2. **Identify cross-provider abstractions.** Look for: a `PaymentGateway` / `PaymentProvider` interface, a strategy or factory pattern, shared DTOs for payment requests/responses, a unified webhook pipeline (verify → enqueue → dedupe → reconcile), a shared retry/backoff utility, a project-wide error taxonomy that providers map into.
3. **Decide whether to mirror.** Only mirror when there's evidence of a **clear cross-provider pattern**: ≥2 providers already slotted into the same interface, **or** one provider plus a clearly generic abstraction. If the project has only one prior provider with no abstraction — or no payment code at all — follow Nopan's canonical examples instead of overfitting to a one-off.

### What to mirror, concretely

| Layer | What it usually looks like | What to copy for Nopan |
|---|---|---|
| Folder structure & naming | `src/payments/<provider>/`, `<Provider>Client`, `<Provider>WebhookHandler` | Same depth, same naming convention → `src/payments/nopan/`, `NopanClient`, `NopanWebhookHandler` |
| Abstractions / interfaces | `PaymentGateway` interface, `PaymentRequest`/`PaymentResponse` DTOs | Implement the interface; map Nopan request/response shapes onto the existing DTOs rather than introducing parallel types |
| Webhook pipeline | Controller returns 2xx fast → raw-body signature verification → queue → dedupe → reconcile | Reuse the same controller shape, queue topic format, dedupe store, and reconciliation step — do not build a parallel pipeline |
| Error mapping & retry | Internal `PaymentError` taxonomy, shared retry/backoff utility, shared idempotency-key generator | Translate Nopan `reasonCode` families into the existing taxonomy; reuse the retry utility and idempotency strategy already in use |

### When mirroring conflicts with Nopan requirements

Nopan's non-negotiable requirements — mTLS, RFC-9421 request signing, response signature verification, `Idempotency-Key` on mutating calls — may not fit the project's existing shared HTTP client. If you hit that, **surface it to the user before forking off**; don't silently bypass the abstraction or silently break Nopan's requirements. Common resolutions: extend the shared client to support per-provider TLS material and request interceptors; or add a Nopan-specific transport layer below the shared `PaymentGateway` interface.

### When there's nothing to mirror

If the codebase has no prior payment-provider integration, say so to the user, then proceed with Nopan's canonical examples from the topic guides. Don't invent project-wide abstractions on the user's behalf in that case — implement Nopan directly and let the user decide later if a generic layer is worth the cost.

## Environments

| Environment | API base URL | Portal |
|---|---|---|
| Sandbox | `https://api.sandbox.nopan.dev` | `https://portal.nopan.com/sandbox` |
| Production | `https://api.nopan.io` | `https://portal.nopan.com/production` |

The OpenAPI spec is browsable at [`/api`](https://docs.nopan.com/api).

## What every Nopan request needs

Every request — including the OAuth token request — requires **all three** of the following. Skipping any one will fail.

1. **mTLS** with a client certificate signed by a Nopan-trusted CA (TLS 1.3 required).
2. **OAuth 2.0 Bearer access token** in `Authorization: Bearer <token>`, obtained from `POST /auth/token` via `client_credentials`.
3. **HTTP Message Signature (RFC 9421)** built from request components, signed with the client's private signing key. The token request itself is also signed.

In addition, **mutating operations require an `Idempotency-Key` header** (UUID). See `nopan-idempotency` guidance inside [`nopan-payments`](https://docs.nopan.com/skills/nopan-payments.md).

For the full layered model, fetch [Authentication Overview](https://docs.nopan.com/guides/authentication/authentication-overview).

## Pick the right topic guide

| The user is working on… | Use this guide |
|---|---|
| Client certificates, signing keys, token requests, signature headers | [`nopan-authentication`](https://docs.nopan.com/skills/nopan-authentication.md) |
| Initiating / finalizing / charging / capturing / refunding / canceling payments, payment lifecycle, status polling | [`nopan-payments`](https://docs.nopan.com/skills/nopan-payments.md) |
| Receiving event notifications, configuring callbacks, verifying webhook signatures | [`nopan-webhooks`](https://docs.nopan.com/skills/nopan-webhooks.md) |
| Sandbox flows, mocking outcomes, Postman, end-to-end testing | [`nopan-testing`](https://docs.nopan.com/skills/nopan-testing.md) |
| HTTP error codes, Nopan `reasonCode` values, retry strategy, troubleshooting | [`nopan-errors`](https://docs.nopan.com/skills/nopan-errors.md) |

If the user's task spans multiple areas (the common case for a from-scratch integration), chain the guides in this order: **Step 0 discovery (above) → authentication → payments → webhooks → testing → errors**. Each topic guide assumes Step 0 has happened — it describes Nopan's mechanics, not the shape of the code, which should come from the project's existing patterns.

## Recommended integration order

The platform's own walkthrough lays this out at [Integration Overview](https://docs.nopan.com/guides/integration-walkthrough):

1. **Request a sandbox account** via `support@nopan.com`. Nopan provisions an organization, a default admin user, a contracting entity, and a processing account.
2. **Provision credentials** — generate mTLS client cert and a separate signing key pair; register the public signing key in the portal; note the returned `Signing Key ID`.
3. **Obtain an access token** from `/auth/token` (this request is itself mTLS + signed).
4. **Make a first signed API call** (e.g. `POST /payments/initiate`) against the sandbox.
5. **Wire up webhooks** to receive lifecycle events instead of polling.
6. **Test with mocks** (Standard Mock or Pass-Through) before involving real schemes.
7. **Complete the [Go-Live Checklist](https://docs.nopan.com/guides/integration-walkthrough#go-live-checklist)** to enable production.

## Key concepts to learn early

- **Accounts model** — Organization → Contracting Entity → Processing Account. See [Accounts](https://docs.nopan.com/concepts/accounts). The `processingAccountId` appears in API requests.
- **CIT vs MIT** — Customer-Initiated Transactions start with `/payments/initiate` + `/payments/finalize`; Merchant-Initiated Transactions start with `/payments/charge`. See [Payment Lifecycle](https://docs.nopan.com/concepts/lifecycle).
- **Scopes** — `payments:read` (default), `payments:process` (must request), `data:reports` (must request).
- **Supported payment methods** — listed under [`/payments/*`](https://docs.nopan.com/payments/payments-overview) on docs.

## When to fetch the docs

These guides are intentionally lean. Fetch the live URL when you need:

- A current request or response payload shape → [OpenAPI](https://docs.nopan.com/api).
- The list of webhook event types → [Webhook Types](https://docs.nopan.com/guides/webhooks/webhook-types).
- The full error code reference → [Error Handling](https://docs.nopan.com/guides/errors).
- A specific payment method's quirks → [Payment Methods](https://docs.nopan.com/payments/payments-overview).

## Support

- Email: `support@nopan.com`
- Detailed escalation paths: [Support](https://docs.nopan.com/guides/support).