canonical: https://jentic.com/apis/nuapay.com/nuapay # Nuapay TPP API Specification Jentic publishes the only available OpenAPI specification for Nuapay TPP API Specification, keeping it validated and agent-ready. Nuapay is a regulated PSD2 third-party provider that initiates open-banking payments directly from a payer's bank account across the UK and EU. The TPP API exposes payment initiation, refund, payment history, and bank discovery endpoints for merchants and partner integrators that want to bypass card rails. It is used by SaaS billing, e-commerce checkouts, and B2B collections where Pay-by-Bank is preferred over card networks. ## For AI agents Initiate PSD2 open-banking payments and refunds, browse supported banks, and query payment status across the Nuapay TPP network. ## Scope Does not handle card processing, KYC onboarding, or accounting reconciliation - use for PSD2 open-banking payment initiation and refunds only. ## Capabilities - Initiate a Pay-by-Bank payment from a payer's bank account - Retrieve a payment record and its current open-banking status - List all payments created by a merchant or partner - Retry a failed or expired payment initiation - Refund a previously settled open-banking payment - Browse supported bank families and individual banks for payer selection - Inspect the event history of a specific payment for audit and reconciliation ## Use cases ### Pay-by-Bank Checkout Merchants offer Pay-by-Bank as a checkout option to avoid card processing fees. The flow starts with POST /payments, the customer authenticates at their bank, and the merchant polls GET `/payments/{paymentId}` until the open-banking status confirms settlement. Nuapay handles the regulated AISP and PISP flows in the background. Example prompt: Call POST /payments with the order amount and payer bank, then poll GET `/payments/{paymentId}` until the status reaches settled ### Bank Selection and Discovery Checkout pages render a bank picker driven by GET /bankfamilies and GET /banks so the payer can choose their institution before authorisation. The endpoints return logos, identifiers, and payment-rail support that the front end uses to filter selectable banks. Example prompt: Call GET /bankfamilies, then GET /banks to populate a bank picker for an open-banking checkout ### Refunds and Payment History Operations teams reconcile open-banking flows by calling GET `/payments/{paymentId}/history` for the full event timeline and POST `/payments/{paymentId}/refunds` to push money back to the payer. Refunds and history are scoped to a specific payment ID to preserve audit trails. Example prompt: Call POST `/payments/{paymentId}/refunds` with the refund amount, then GET `/payments/{paymentId}/refunds/{refundId}` to confirm status ### Agent-Driven Open-Banking Workflow An AI agent initiates Pay-by-Bank checkouts on behalf of a finance team, polls payment status, and triggers refunds when an order is cancelled. Through Jentic the agent searches for 'initiate open banking payment', loads the POST /payments schema, and executes without learning Nuapay's TPP-specific OAuth flow. Example prompt: Search Jentic for 'initiate open banking payment', load the schema for POST /payments, and execute with the merchant ID and amount ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/payments` | Create an open-banking payment | | GET | `/payments/{paymentId}` | Retrieve a payment by ID | | PATCH | `/payments/{paymentId}` | Retry a payment | | GET | `/payments/{paymentId}/history` | Retrieve payment event history | | POST | `/payments/{paymentId}/refunds` | Refund a payment | | GET | `/bankfamilies` | List bank families | | GET | `/banks` | List supported banks | ## Key resources - **Payments** — Initiate, list, retry, retrieve, and inspect history of open-banking payments - **Refunds** — Create and list refunds against settled payments - **Banks** — Browse supported bank families and individual banks for payer selection ## Why Jentic - **Setup:** Wiring the Nuapay TPP API by hand means handling both HTTP basic keys and an OAuth 2.0 password flow, carrying the right open-banking scopes into calls to api.nuapay.com/tpp, and mapping payment initiation, refunds, and bank lookups yourself. Through Jentic you install once, import the Nuapay TPP API from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** Nuapay puts the payment id in the URL path (`/payments/{paymentId}`), so a rule can pin your agent to one payment: it can read that payment's status and history and nothing else. You choose the operations it may call, so initiating payments and posting refunds are not included unless you add them. - **Credential handling:** Your Nuapay merchant and partner credentials, including the API keys and OAuth2 client secrets, are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'initiate an open banking payment' or 'refund a pay-by-bank transaction', and Jentic returns the matching Nuapay operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Stripe** — Card-first payment processor with optional bank-debit rails - **Plaid** — Bank-account verification and balance data that pairs with open-banking payments - **Adyen Checkout** — Global checkout API with open-banking method support among many ## FAQ ### Why is there no official OpenAPI spec for Nuapay TPP API Specification? Nuapay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Nuapay TPP API Specification via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Nuapay TPP API use? The spec defines four schemes: MerchantApiKey and PartnerApiKey for HTTP key auth, plus MerchantOAuth2 and PartnerOAuth2 client-credentials flows. Through Jentic the appropriate credential is stored in the vault and injected at execution, so the agent never holds the raw key or token. ### Can I retry a payment that failed at the bank? Yes. PATCH `/payments/{paymentId}` retries a payment whose initiation expired or failed before the payer authenticated. Use this rather than creating a brand-new payment so the audit trail remains continuous. ### How do I refund an open-banking payment through Jentic? Search Jentic for 'refund open banking payment', load the schema for POST `/payments/{paymentId}/refunds`, and execute with the refund amount. Jentic injects the merchant credential and returns the created refund record. ### What are the rate limits for the Nuapay TPP API? The OpenAPI spec does not declare explicit rate limits. Nuapay applies regulated TPP limits and merchant-tier quotas in production; check your Nuapay dashboard or contact your account manager for the limits attached to your client ID. ### How do I show a bank picker on my checkout? Call GET /bankfamilies to list grouped institutions, then GET /banks to render individual selectable banks with logos and identifiers. Filter by country and the payment rails the bank supports before showing the picker. ### Can I limit what my agent is allowed to do with the Nuapay TPP API? Yes. Jentic One is self-hosted, so your own rules decide which operations and credentials the agent may use: because Nuapay puts the payment id in the URL path (`/payments/{paymentId}`), a rule can pin the agent to a single payment and let it read only that payment's status and history. You choose the operations it may call, so initiating payments and posting refunds are excluded unless you explicitly add them.