> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/api-overview/overview.md).

# Overview

**Who connects to Nexus**

Nexus exposes APIs to two kinds of counterparty: Instant Payment System Operators (IPSOs) and FX Providers (FXPs). Payment Service Providers (PSPs) and Settlement Account Providers (SAPs) do not connect to Nexus directly; they reach Nexus through their domestic instant payment system (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 multiple API families:

1. **Payments and Connectivity API (IPSO-facing)**
   * Payment Setup APIs are synchronous JSON (read-only requests). It gathers what is needed to build a valid payment: country and currency reference data, address types and input rules, the financial-institution directory, and either an FX quote or, where the PSP provides its own FX, the fee and amount computation. Reference data can be cached and refreshed efficiently using ETags.
   * Payment Processing APIs are a-synchronous ISO 20022 XML under `/iso20022`, with one endpoint per message type, and it runs in both directions:
     * The Source IPSO submits pacs.008, pacs.002, pacs.028, camt.029, acmt.023, acmt.024, admi.002 and admi.004 to Nexus.
     * The Destination IPSO must also host its own receiving endpoints for the messages Nexus delivers to it: pacs.008, pacs.002, pacs.028, acmt.023, acmt.024, camt.056, admi.002 and admi.004.
     * Submissions are acknowledged with `202 Accepted`. This means the message has been received for processing, not that the payment has succeeded. The business response arrives later as a separate message.
   * Connectivity APIs provide two checks. The Heartbeat API asks whether the other party is reachable. The Health check API asks whether the other party's system is healthy with capability to process a request end-to-end with all security controls applied. Both Nexus will and the IPSO should implement and host them, so connectivity can be checked in either direction. They are optional for IPSOs but strongly recommended.
2. **Operations API (IPSO-facing):** give the IPSO access to information on its own transactions and to the Nexus Service Desk. It covers:

   * retrieving the daily camt.054 reconciliation report
   * querying transaction-level data (Operational Data Feed)
   * checking the latest status of a single payment by its UETR (Track and Trace)
   * raising Service Desk requests

   Each IPSO sees only the transactions it is party to, and no personal data is returned.
3. **FXP API:** FX Providers (FXPs) publish and maintain exchange rates, 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 and Connectivity):** connectivity is over an IPsec IKEv2 VPN tunnel and nothing is reachable from the public Internet. Each side addresses the other by hostname, resolved through private DNS over the tunnel: Nexus private DNS for Nexus hosts, the IPSO’s own private DNS for IPSO hosts. The same controls apply in both directions:
  * Every request carries mutual TLS (TLS 1.3) plus an OAuth 2.0 client-credentials token that is certificate-bound ([RFC 8705](https://www.rfc-editor.org/info/rfc8705/)), so a token cannot be replayed from a different connection.
  * When Nexus calls the IPSO, Nexus obtains its token from the IPSO’s own authorization server.
  * Every request in both directions is also signed and verified using [RFC 9421 HTTP Message Signatures](https://datatracker.ietf.org/doc/html/rfc9421), and Nexus signs its responses to GET requests.
* **IPSO (Operations):** the same mutual TLS and certificate-bound OAuth 2.0 controls apply, but on a separate path. Operations APIs use a separate and dedicated Reporting and Operations VPN tunnel and its own hostname.
  * Note: The exception is Track and Trace, which uses the above payment connection and credentials.
* **FXP:** mutual TLS validated at the CDN edge (fail-closed, certificate never forwarded as a header) plus an OAuth 2.0 bearer token.
* **Scopes:** every operation declares the exact OAuth 2.0 scope it requires, for example `countries.read`, `payment.process`, `connectivity.check` or `Operations.reports`. A token issued for one API family (e.g. IPSO (Payments and Connectivity)) therefore cannot be used to call another API family (e.g. FXP).