--- name: nopan-payments description: Apply this guide when implementing Nopan payment flows — initiating, finalizing, charging, capturing, refunding, or canceling payments, or working with payment lifecycle and status. Covers Customer-Initiated and Merchant-Initiated transactions, idempotency, status polling, and the supported payment methods (BLIK, Bizum, Iris, Satispay, Wero, and other A2A methods). Pairs with `nopan-authentication` (every call must be authenticated) and `nopan-webhooks` (lifecycle events are pushed via webhook). --- # Nopan payments This guide covers the payment domain: the lifecycle, the endpoints, and the rules that don't change with releases. Schemas and exact field lists live in the OpenAPI spec — fetch them when needed. > Browse the OpenAPI: [https://docs.nopan.com/api](https://docs.nopan.com/api). Lifecycle reference: [Payment Lifecycle](https://docs.nopan.com/concepts/lifecycle). > **Match existing patterns** — if the project has a `PaymentGateway` / `PaymentProvider` interface or shared payment DTOs used by another payment-provider integration, implement Nopan as another conforming implementation rather than a standalone client. Map Nopan's request/response shapes onto the existing types; do not introduce parallel ones. The endpoint and lifecycle rules below describe *what Nopan does*, not *how your code should be organized*. See [`nopan-integration`](https://docs.nopan.com/skills/nopan-integration.md) Step 0. ## Two flow shapes — CIT vs MIT The first decision when starting a payment is which flow applies. ### CIT — Customer-Initiated Transactions The shopper is present (e.g. checkout). Most CIT flows require Strong Customer Authentication (SCA) and involve a redirect to the shopper's bank or wallet. ``` POST /payments/initiate → start the payment, get a redirect URL / next-step instructions → shopper authenticates with the scheme POST /payments/finalize → complete onboarding + authorize with the scheme → if autoCapture=true, this also captures [POST /payments/capture] → optional, only when autoCapture=false (delayed capture) → settlement happens automatically after capture [POST /payments/refund] → optional, after the payment is settled ``` See [`/payments/initiate`](https://docs.nopan.com/api#tag/Payment-Processing-APIs/operation/initiatePayment) and [`/payments/finalize`](https://docs.nopan.com/api#tag/Payment-Processing-APIs/operation/finalizePayment). ### MIT — Merchant-Initiated Transactions Used for recurring payments or credentials-on-file. No active shopper interaction. A valid mandate must already exist. ``` POST /payments/charge → authorize (and capture if autoCapture=true) [POST /payments/capture] → optional, only when autoCapture=false [POST /payments/refund] → optional, after the payment is settled ``` See [`/payments/charge`](https://docs.nopan.com/api#tag/Payment-Processing-APIs/operation/chargePayment), [Recurring Payments](https://docs.nopan.com/concepts/recurring-payments), and [Stored Credentials](https://docs.nopan.com/concepts/stored-credentials). ## Endpoint cheat sheet | Endpoint | Method | Purpose | Idempotency-Key required? | |---|---|---|---| | `/payments/initiate` | POST | Start a CIT payment | yes | | `/payments/finalize` | POST | Finish authorization after SCA (CIT) | yes | | `/payments/charge` | POST | Authorize a MIT payment | yes | | `/payments/capture` | POST | Move funds after authorization | yes | | `/payments/cancel` | POST | Void an authorization that hasn't been captured | yes | | `/payments/refund` | POST | Return funds on a settled payment | yes | | `/payments/{transactionId}/status` | GET | Current status snapshot | no | | `/payments/{transactionId}/events` | GET | Event history for a payment | no | Always fetch the OpenAPI for the current request/response shape — these are not duplicated here on purpose. ## Required headers on every call Covered in detail by the `nopan-authentication` guide, but worth restating here because forgetting one is the most common failure mode: ``` Authorization: Bearer Idempotency-Key: # on every mutating call Signature: nopan_sig=:: Signature-Input: nopan_sig=(...);keyid="...";created= Content-Type: application/json Content-Digest: sha-256=:: Content-Length: ``` ## Idempotency keys - Required on **all** state-changing payment endpoints (`initiate`, `finalize`, `charge`, `capture`, `cancel`, `refund`). - Use a fresh UUID per **logical operation**, not per HTTP retry. Replaying the same key with the same payload returns the original response. - Replaying the same key with a **different** payload returns `409 Conflict` (`reasonCode 3xxx`). - Reference: [Idempotency Keys](https://docs.nopan.com/guides/idempotency-keys). ## Tracking status There are two complementary mechanisms — **prefer webhooks** for real-time progress, **use status polling** as a fallback or for explicit confirmation. - Webhooks: configure once, react to events asynchronously → [`nopan-webhooks`](https://docs.nopan.com/skills/nopan-webhooks.md). - Polling: `GET /payments/{transactionId}/status` and `GET /payments/{transactionId}/events`. Use sparingly to avoid rate limits. Status values are documented in [Payment Lifecycle](https://docs.nopan.com/concepts/lifecycle) — they cover initiation, authorization, capture, settlement, refund, and terminal states (success / fail / cancel / expire). ## Operational rules that won't change - **Authorization-only payments must be either captured or canceled** before they expire on the scheme side; otherwise funds stay locked then fall off. - **Refunds are only allowed on settled payments.** A pre-settlement reversal is a `cancel`, not a refund. - **Partial captures and partial refunds** are scheme-dependent. Check the payment method docs at [Payment Methods](https://docs.nopan.com/payments/payments-overview) before assuming support. - **`autoCapture` is set on the initiating call.** If `true`, `finalize` (CIT) or `charge` (MIT) captures immediately; no separate `/payments/capture` is needed. - **Settlement is automatic** after a successful capture — there is no explicit "settle" endpoint. - **A `clientTransactionId`** is your reference; the `transactionId` returned by Nopan is the canonical identifier used on subsequent calls. - **`processingAccountId`** is required in many payloads. Get it from the portal. ## Reports Settlement and operational data is available via: - `GET /reports` — list reports - `GET /reports/download` — download a specific report Requires the `data:reports` scope on the access token. See [Reports](https://docs.nopan.com/guides/reports). ## Decision rules - **Shopper is present and SCA may be required** → CIT: `initiate` → (redirect/SCA) → `finalize`. - **Recurring or stored-credential charge** → MIT: `charge` directly. - **Want one-step authorize+capture** → set `autoCapture=true` on the initiating call. - **Want delayed settlement (warehouse picks the order)** → leave `autoCapture=false`, then call `/payments/capture` later. - **Voiding before settlement** → `/payments/cancel`. **After settlement** → `/payments/refund`. - **Customer asks "did it go through?"** → check the most recent webhook first, then `GET /payments/{transactionId}/status` if the answer is not on hand. - **Got `409` on retry** → the original call already succeeded; do not invent a new idempotency key. ## Payment methods Currently documented: BLIK, Bizum, Iris, Satispay, Wero. Each has scheme-specific quirks (test codes, redirect handling, capture support). Fetch the method's page from [Payment Methods](https://docs.nopan.com/payments/payments-overview) **before** writing scheme-specific code. ## Related guides - Authenticating each request → [`nopan-authentication`](https://docs.nopan.com/skills/nopan-authentication.md). - Receiving lifecycle events → [`nopan-webhooks`](https://docs.nopan.com/skills/nopan-webhooks.md). - Driving outcomes in sandbox → [`nopan-testing`](https://docs.nopan.com/skills/nopan-testing.md). - Interpreting failures and retry rules → [`nopan-errors`](https://docs.nopan.com/skills/nopan-errors.md).