Overview

Who connects to Nexus

Nexus exposes APIs to two kinds of counterparty: Instant Payment System Operators (IPSOs) and FX Providers (FXPs). PSPs and Settlement Account Providers (SAPs) do not connect to Nexus directly and they reach Nexus through their domestic IPS. An IPSO may pass the Nexus APIs through to its participants unchanged or adapt them to domestic conventions; either way, what the IPS exchanges with Nexus must conform to the Nexus specifications.

What this section covers

The specification is one document containing three API families:

1. Payments API (IPSO-facing):

   - Payment Setup is synchronous JSON: country and currency constraints, address types and input rules, the financial-institution directory, FX quotes, and fee/amount computation.

   - Payment Execution is asynchronous ISO 20022 XML under /iso20022, with one endpoint per message type (pacs.008, pacs.002, pacs.028, camt.029, acmt.023, acmt.024, admi.002, admi.004). Submissions are acknowledged with 202 Accepted; the business response arrives later as a separate message.

2. Health Check API (IPSO-facing, read-only): answers two questions: is Nexus Payment Processing up on a given gateway or region, and is a destination IPSO active or suspended?

3. FXP API: FX Providers (FXP) publishes and maintains: exchange rates (keyed by source/destination IA account, live until replaced or withdrawn), tier-based rate improvements, FXP-PSP relationships, and a query of completed payments where the FXP provided the rate.

Security model - differs by counterparty

• IPSO (Payments): connectivity is over an IPsec IKEv2 tunnel with endpoints resolved via Nexus private DNS and nothing is reachable from the public Internet. Every request carries mutual TLS plus an OAuth 2.0 client-credentials token that is certificate-bound (RFC 8705), so a token cannot be replayed from a different connection. ISO 20022 messages are additionally signed with secret key and headers (X-Nexus-Signature, X-Nexus-Timestamp, X-Nexus-Key-Id).

• IPSO (Health Check): OAuth 2.0 only; scopes confine each IPSO to its own gateways and counterpart IPSOs.

• FXP: mutual TLS validated at the CDN edge (fail-closed, certificate never forwarded as a header) plus an OAuth 2.0 bearer token.

• Every operation declares the exact OAuth 2.0 scope it requires, so a token minted for one API family (e.g. IPSO (Payments)) cannot be used to call another API family (e.g. FXP).