{ "openapi": "3.1.0", "info": { "title": "Nexus Operations IPSO API", "version": "0.4.0", "description": "Retrieve the daily Reconciliation Report, consume the Operational Data Feed, track and trace a single payment, and raise Service Desk catalog items with NGO, NGP, a counterparty IPSO or a selected FXP.\n\nTrack and Trace is the one operation that does not use the Operations reporting path. It reads live payment records, so it is served on the Payment Processing host under payment API authentication; every other operation uses the Operations host, authorization server and credentials.\n\nEvery channel returns only transactions to which the IPSO is party. APIs require the IPSO's Operations credentials, the capability's OAuth scope and certificate-bound mTLS; human grants do not confer machine scopes. `Cache-Control: no-store` governs HTTP caching, not authorised processing and retention of retrieved business data in IPSO systems. Never retain or log signed URLs as business data.\n\nEvery request, whatever its HTTP method, carries an RFC 9421 HTTP message signature in the Signature-Input and Signature headers (algorithm rsa-pss-sha512, label nexus, tag nexus-v1, created/expires within ±5 minutes), and a request with a body also carries an RFC 9530 Content-Digest (sha-512). Requests to the Operations host are signed with the IPSO's Operations signing key pair; Track and Trace is signed with the IPSO's payment signing key pair. Nexus signs every GET response, and the IPSO MUST verify the response signature before using the response. A missing or invalid request signature is rejected with 401 AE005 MESSAGE_SIGNATURE_INVALID. The Reconciliation Report file download through its pre-signed URL is not an API call and carries no RFC 9421 signature; its integrity rests on the SHA256 checksum in the signed manifest response and on the file's own signature." }, "servers": [{"url": "https://{environment}.operations.nexus.net", "description": "Operations reporting endpoint.", "variables": {"environment": {"default": "prod", "enum": ["pat", "prod"], "description": "Deployment environment subdomain."}}}], "x-controls-version": "2026-10-02", "x-publication-gates": ["Actual server, token endpoint, issuer, audience and certificate trust, for both the Operations and the Payment Processing paths", "Track and Trace OAuth scope name", "Operations signing-key registry and the onboarding channel for exchanging Operations signing public keys", "ISO status/source mapping and complete-file acceptance evidence", "Service-request scope provisioning, cross-participant communication entitlements and approved ServiceNow profile mappings", "Registered identifier formats for NGP and FXP service-request recipients", "Durable intake and downstream deduplication evidence; authorised Service Desk lookup by NGO requestId and operational recovery for failed routing", "Debtor and creditor account identifiers in the Payment Processing reporting contract"], "x-request-intake-policy": { "appliesTo": ["submitServiceRequest"], "identity": "Derive submitting IPSO and environment exclusively from validated Operations credentials. A recipient is a routing target, never an override of caller identity or data access. Record the authenticated service principal, IPSO, environment and server acceptance time; no human submitter is inferred from client credentials.", "authorisation": "Require the create scope and profile entitlement. An IPSO or FXP recipient must be registered, active, different from the sender and eligible for communication from that sender in the authenticated environment; NGO and NGP recipients require the corresponding profile entitlement. Recheck recipient eligibility before downstream delivery. Unknown, inactive, self, cross-environment and unauthorised recipient targets receive the same non-disclosing 403. Only the sender, intended recipient and authorised NGO support personnel may access the record.", "admission": "Reject duplicate JSON member names, unknown fields, unsupported code/version/recipient combinations and disallowed content before acceptance. Atomically reserve the IPSO/environment/operation/idempotency-key binding, immutable receipt, approved routing-profile revision and durable routing work with the new-submission allowance. Failure to commit any part returns no acceptance. No rejected attempt consumes a new-submission allowance or reserves a new key.", "idempotency": "Fingerprint the parsed JSON body, ignoring object-member order and insignificant JSON whitespace but preserving string values, scalar types and array order. The same scoped key and body returns the original 202 receipt, requestId and acceptedAt without another submission, routing item or business-allowance unit. A changed body returns 409 BE912 IDEMPOTENCY_KEY_CONFLICT. Concurrent duplicates must have the same outcome. Authenticate and authorise every retry; transport rate and concurrency guards still apply.", "retention": "Publish the idempotency replay window and request-retention period before activation. Retain key, fingerprint and receipt for at least the replay window and while delivery is unresolved, even if the downstream record closes. Clients never reuse a key for another submission or retry after the published window; contact Service Desk with the key or known requestId to resolve uncertainty. Do not silently expire an unresolved submission into a second create.", "routing": "Nexus accepts the service request; Service Desk owns fulfilment. Snapshot the approved profile mapping at acceptance so later catalog changes do not reinterpret queued work. Resolve ServiceNow catalog identifiers and fulfilment groups internally. Every downstream write carries requestId as nexus_correlation_id; enforce uniqueness and reconcile uncertain create outcomes before retrying. Recheck current delivery authorisation without changing the accepted profile semantics. Persistent failures enter a monitored recovery queue, retain the original receipt and are handled by authorised NGO staff; never silently discard accepted work.", "content": "One UTF-8 application/json object per call, at most 65536 bytes; no batches or content encoding other than identity. Subject and description are plain text, never executable markup. No customer PII, credentials, private keys, payment-message bodies, attachments, attachment URLs or base64 files, including inside free text. Screen content before acceptance, render it as text and never interpret it as routing instructions or an approval. Log only safe identity, requestId, profile/version, outcome and timing metadata, not payloads, free text, tokens or raw idempotency keys." }, "security": [{"nexusOAuth": [], "mutualTLS": []}], "tags": [ {"name": "Reconciliation Report", "description": "Reconciliation Report: retrieval of the authoritative daily report."}, {"name": "OperationalDataFeed", "description": "Operational Data Feed: transaction-level operational data by API, the same data set presented on the Transaction Dashboard."}, {"name": "TrackAndTrace", "description": "Track and Trace: the latest known state of a single transaction by UETR. Served on the Payment Processing host under payment API authentication, not the Operations reporting path."}, { "name": "ServiceRequests", "description": "The endpoint enables authorized direct participants to create a new ServiceNow ticket through the API. Each accepted submission creates a new ticket, classified as either a Case or a Service Request.\n\n### Service catalog: category and item\n\nThe catalog below is the complete set of items an IPSO or direct participant may raise through this endpoint. Items are grouped by **primary catalog**, the category they belong to; each row is one sub-catalog item, selected with its request code. Every submission carries both `requestCode` and `category`, and the pair is fixed by the catalog: a category that does not match its code is rejected rather than corrected.\n\nNGO operates the intake in every case; the recipient column names the party that owns fulfilment.\n\n| Primary catalog | Sub-catalog item | Category | Request code | Recipient | Description | Primary IPSO role |\n| --- | --- | --- | --- | --- | --- | --- |\n| Participant Support & Requests | Request for Technical support or enquiries | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `TECHNICAL_SUPPORT` | NGO | Requests technical support or raises an enquiry: development-related enquiries, account-management service support, or any other technical enquiry. | Technical Operations User, Developer |\n| Participant Support & Requests | Raise Participant General Support Request/ Enquires | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `PARTICIPANT_SUPPORT` | NGO | Submits a general support request or enquiry to obtain NGO assistance with a Nexus service. | All IPSO roles |\n| Participant Support & Requests | mTLS Certificate Expiry Support Request | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `MTLS_CERTIFICATE_EXPIRY` | NGO | Coordinates renewal of a participant certificate approaching or past expiry. Suspected compromise is a security incident, not an expiry request. | Technical Operations User |\n| Participant Support & Requests | Request Confidential Information Disclosure | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `CONFIDENTIAL_DISCLOSURE_REQUEST` | NGP | Requests NGP-authorised disclosure of confidential information to support a permitted external release. | Business Operations User |\n| Participant Support & Requests | Request Nexus Portal and PAT Integration Support | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `NEXUS_PORTAL_SUPPORT` | NGO | Requests Nexus Portal or PAT integration support to resolve a non-incident development or testing issue. | Developer, Technical Operations User |\n| Participant Support & Requests | Request Participant Reference Data Change | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `REFERENCE_DATA_CHANGE` | NGO | Requests a reference-data change to keep the participant's authoritative information accurate in the required environment. | Business Operations User |\n| Participant Support & Requests | Raise Payment Recall Request | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `PAYMENT_RECALL` | IPSO | Sends a payment recall request to the counterparty to seek return of a payment, before a formal dispute is warranted. Full original amount only. | Business Operations User |\n| Participant Support & Requests | Request Further Payment Information | `PARTICIPANT_SUPPORT_AND_REQUESTS` | `PAYMENT_INFORMATION_REQUEST` | IPSO | Requests further payment information from the counterparty to clarify a payment before escalation. | Business Operations User |\n| Participant Management | Submit IPSO Onboarding Application | `PARTICIPANT_MANAGEMENT` | `IPSO_ONBOARDING_APPLICATION` | NGO | Sends qualified participant details to NGO to start technical onboarding, after off-system qualification. | Business Operations User |\n| Participant Management | Submit PSP Onboarding Application | `PARTICIPANT_MANAGEMENT` | `PSP_ONBOARDING_APPLICATION` | NGO | The sponsoring IPSO submits a PSP onboarding application to establish the indirect participant's approved Nexus relationship and readiness. | Business Operations User |\n| Participant Management | Submit SAP Onboarding Application | `PARTICIPANT_MANAGEMENT` | `SAP_ONBOARDING_APPLICATION` | NGO | The sponsoring IPSO submits an SAP onboarding application to establish the indirect participant's approved Nexus relationship and readiness. | Business Operations User |\n| Participant Management | Submit PDO Onboarding Application | `PARTICIPANT_MANAGEMENT` | `PDO_ONBOARDING_APPLICATION` | NGO | The sponsoring IPSO submits a PDO onboarding application to establish the indirect participant's approved Nexus relationship and technical readiness. | Business Operations User |\n| Participant Management | Submit CBDDQ / FXP KYB Request | `PARTICIPANT_MANAGEMENT` | `FXP_KYB_REQUEST` | FXP | The sponsoring IPSO submits CBDDQ and FXP KYB information for its PSP to obtain selected-FXP approval and activate approved relationships. | Business Operations User |\n| Participant Management | Request Direct Participant Withdrawal | `PARTICIPANT_MANAGEMENT` | `DIRECT_PARTICIPANT_WITHDRAWAL` | NGO | Submits a written withdrawal request to begin the participant's governed offboarding from Nexus. | Business Operations User |\n| Incident & Availability Management | Report a Technical incident | `INCIDENT_AND_AVAILABILITY_MANAGEMENT` | `TECHNICAL_INCIDENT` | NGO | Reports a service disruption as an ITSM Incident to restore affected Nexus availability or performance. | Technical Operations User |\n| Incident & Availability Management | Report a security Incident | `INCIDENT_AND_AVAILABILITY_MANAGEMENT` | `SECURITY_INCIDENT` | NGO | Reports a security issue as an ITSM Incident to protect Nexus services and data. | Technical / Security Operations User |\n| Incident & Availability Management | Report unplanned Current Participant Outage | `INCIDENT_AND_AVAILABILITY_MANAGEMENT` | `PARTICIPANT_OUTAGE` | NGO | Reports a current outage on the IPSO's own system, where no recovery is yet confirmed. The Payment Processing API is the primary channel; this intake is the alternative when the payment flow is unavailable. | Technical Operations User, Business Operations User |\n| Incident & Availability Management | Notify Planned IPSO Downtime or Recovery | `INCIDENT_AND_AVAILABILITY_MANAGEMENT` | `PLANNED_DOWNTIME` | NGO | Notifies NGO in advance of planned downtime or recovery. The Payment Processing API is the primary channel; this intake is the alternative when the payment flow is unavailable. | Technical Operations User, Business Operations User |\n| Dispute & Resolution Management | Raise Formal Dispute \u2014 Transaction Processing | `DISPUTE_AND_RESOLUTION_MANAGEMENT` | `DISPUTE_TRANSACTION_PROCESSING` | IPSO | Raises a formal transaction-processing dispute after bilateral efforts fail, where one transaction remains unresolved. | Business Operations User |\n| Dispute & Resolution Management | Raise Formal Dispute \u2014 Fraud or Scam | `DISPUTE_AND_RESOLUTION_MANAGEMENT` | `DISPUTE_FRAUD_OR_SCAM` | IPSO | Raises a formal fraud or scam dispute after bilateral efforts fail. | Business Operations User |\n| Dispute & Resolution Management | Raise Formal Dispute \u2014 Scheme Non-Compliance | `DISPUTE_AND_RESOLUTION_MANAGEMENT` | `DISPUTE_SCHEME_NON_COMPLIANCE` | IPSO | Raises a formal scheme non-compliance dispute where the responding counterparty has not resolved the alleged rule breach. | Business Operations User |\n| Dispute & Resolution Management | Report Reconciliation Discrepancy | `DISPUTE_AND_RESOLUTION_MANAGEMENT` | `RECONCILIATION_DISCREPANCY` | IPSO | Reports a reconciliation discrepancy for formal resolution where counterparties cannot resolve a payment or settlement mismatch directly. | Business Operations User |\n| Dispute & Resolution Management | Raise Scheme Fee Calculation or Report Query | `DISPUTE_AND_RESOLUTION_MANAGEMENT` | `SCHEME_FEE_QUERY` | NGP | Raises a Scheme Fee calculation or report query for NGP investigation, to understand or correct calculation and source-data issues. | Business Operations User |\n| Feedback & Complaint | Raise a Feedback and Complaint to Nexus | `FEEDBACK_AND_COMPLAINT` | `FEEDBACK_AND_COMPLAINT` | NGO | Submits feedback or a complaint on areas of improvement in the Nexus service, to obtain a documented investigation and resolution. | Business Operations User |\n\n### Scope boundaries\n\nPayment recall is raised by the Participant, never by an end customer: an end customer asks its PSP, the PSP provides the case to its IPSO, and the IPSO raises the Nexus-facing request. A recall concerns one original payment, for its full amount only. Where it is accepted, the destination side initiates a separate Return Payment referencing the original UETR; the original payment retains its finality.\n\nA dispute item is for a matter that is already formal and unresolved. Routine status questions, report requests and technical issues belong to the support, incident and enquiry items, or to Track and Trace; raising one of those first does not prevent a later dispute.\n\nCatalog items sourced by NGO, NGP, FXP or Nexus automation are outside this IPSO-facing intake, including automated severity incidents, the automated investigation inquiry for non-final payments, and FX Fee and FX rate maintenance flows.\n\n### Contract evolution\n\nThe request envelope remains stable. New ticket types are added only once the catalog item, its category, schema, authorisation and privacy controls have been approved. Additive fields preserve existing valid submissions; incompatible payload changes introduce a new payloadVersion while supported versions remain accepted. An existing requestCode or payloadVersion is never repurposed." } ], "paths": { "/v1/camt054": { "get": { "tags": ["Reconciliation Report"], "operationId": "getCamt054Download", "summary": "Download the daily Reconciliation Report", "x-release": "Release 1", "description": "Get a secure link to the daily Reconciliation Report. It is the same camt.054 file delivered by SFTP. One request covers one Nexus Day. A request that returns the manifest, including link reissue, consumes one unit of the published retrieval allowance. A 409 REPORT_NOT_READY consumes no allowance unit; repeat requests while the report is not ready are limited to twice per minute and must honour Retry-After. A report published with no transactions is ready and returns 200 with its manifest. A signed link permits download initiation for 300 seconds from issuance; a transfer already started may finish later. Exhausting the allowance returns 429 DAILY_ALLOWANCE_EXCEEDED, and exceeding the not-ready rate returns 429 RATE_LIMIT_EXCEEDED, both with Retry-After.\n\nThe response is the report manifest, with the same field names as the manifest delivered alongside the file on SFTP. Each manifest.files entry carries its own checksums plus a url and expiresAt that exist for this response only. Checksum entries use algorithm/value pairs; SHA256 is the only approved algorithm and must occur exactly once over the protected delivered bytes. Locate it by algorithm, never array position. Additional approved algorithms may be appended; clients tolerate unsupported additional entries without skipping the required SHA256 check or Nexus signature verification.\n\nA report is published as one or more files per IPSO, Nexus Day and closeVersion. sequence is the file's part number starting at 1 and is the final segment of the file name; the highest sequence equals fileCount. Signed URLs and expiry are response-only and must not be persisted or logged. The manifest also names the signature and encryption algorithms and key identifiers the IPSO needs to verify and decrypt the file.\n\nThis request and its 200 response are RFC 9421-signed like every other operation. The file download through the pre-signed url is not a Nexus API call: it carries no Authorization header and no RFC 9421 signature. Verify the downloaded bytes against the SHA256 checksum in this signed manifest, and verify the file's own signature, before use.", "x-usage-limits": {"dailyAllowance": {"limit": 25, "unit": "retrieval-requests"}, "notReadyConsumesDailyAllowance": false, "notReadyRate": {"limit": 2, "windowSeconds": 60, "unit": "requests", "window": "rolling"}, "nexusDaysPerRequest": 1, "signedLinkValiditySeconds": 300}, "security": [{"nexusOAuth": ["Operations.reports"], "mutualTLS": []}], "parameters": [{"$ref": "#/components/parameters/ReportDate"}, {"$ref": "#/components/parameters/SignatureInputBodyless"}, {"$ref": "#/components/parameters/Signature"}], "responses": { "200": { "description": "The published report manifest with per-file checksums and a five-minute download URL. Never log or retain the signed URL as business data.", "headers": {"Cache-Control": {"$ref": "#/components/headers/NoStore"}, "Signature-Input": {"$ref": "#/components/headers/ResponseSignatureInput"}, "Signature": {"$ref": "#/components/headers/ResponseSignature"}, "Content-Digest": {"$ref": "#/components/headers/ResponseContentDigest"}}, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ReportDownload"}, "examples": {"dailyReport": { "summary": "Single-file daily Reconciliation Report", "description": "Illustrative checksums and signed URL. The link is issued at 2026-09-17T02:02:00Z and expires 300 seconds later; generatedAt remains the original report-publication time.", "value": {"manifest": {"manifestVersion": "1.0", "reportType": "CAMT054", "participant": "IPSOMYKL", "nexusDay": "20260916", "closeVersion": 1, "generatedAt": "2026-09-16T16:30:14.000Z", "periodStart": "2026-09-15T16:00:00Z", "periodEnd": "2026-09-16T15:59:59Z", "dataAsOf": "2026-09-16T16:00:00Z", "fileCount": 1, "totalRecords": 489213, "totals": {"ACCC": 489003, "RJCT": 150, "PDNG": 50, "BLCK": 10}, "signature": {"algorithm": "OpenPGP-SHA256", "keyId": "NEXUS-GPG-2026-01"}, "encryption": {"algorithm": "OpenPGP-AES256", "keyId": "IPSOMYKL-GPG-2026-01"}, "files": [{"sequence": 1, "name": "NEXUS_CAMT054_IPSOMYKL_20260916_v1_1.xml.gpg", "records": 489213, "sizeBytes": 734419122, "checksums": [{"algorithm": "SHA256", "value": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}], "url": "https://reports.nexus.net/file?signature=EXAMPLE", "expiresAt": "2026-09-17T02:07:00.000Z"}]}} }} }} }, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/ReportMissing"}, "409": {"$ref": "#/components/responses/ReportPending"}, "410": {"$ref": "#/components/responses/OutsideWindow"}, "429": {"$ref": "#/components/responses/ReportThrottled"}, "500": {"$ref": "#/components/responses/InternalError"}, "503": {"$ref": "#/components/responses/Unavailable"}, "default": {"$ref": "#/components/responses/PerimeterError"} } } }, "/v1/operational-transactions": { "get": { "tags": ["OperationalDataFeed"], "operationId": "listOperationalTransactions", "summary": "Retrieve the Operational Data Feed", "x-release": "Release 1", "description": "Access the Transaction Dashboard's data for automated exception monitoring and operational follow-up. Every first request requires fromDate and toDate: at most 31 inclusive Nexus Days within 13 calendar months, with no future dates. Filter directly by optional status; omitting it includes all source statuses unless another supplied filter narrows them. There is no view parameter or implicit current/pending/overdue/historical population. To retrieve today's activity, set both dates to today in SGT. pendingAgeBucket optionally narrows current PDNG within those dates; it never waives the date range. Date-free single-UETR lookup is provided by Track and Trace, not this feed.\n\n### Relationship to the Reconciliation Report (camt.054)\n\nEach record is a reduced, normalised JSON representation of the corresponding camt.054 `Ntry`: the fields below correspond to camt.054 elements, but the feed is not a lossless copy of every field the file carries. It is not authoritative and is not a camt.054 message; the file remains the authoritative daily record. `uetr` is the primary match key in both channels.\n\n| camt.054 element | Feed field |\n| --- | --- |\n| `Ntry/Amt` + `Ccy` | `entryAmount` |\n| `Ntry/CdtDbtInd` | `creditDebitIndicator` |\n| `Ntry/Sts/Prtry` | `status` |\n| `Ntry/BookgDt/DtTm` | `bookingDateTime` |\n| `Ntry/BkTxCd` | `bankTransactionCode` |\n| `NtryDtls/TxDtls/Refs` | `references` |\n| `AmtDtls/InstdAmt` and `CcyXchg` | `amountDetails.instructedAmount`, `amountDetails.currencyExchange` |\n| `AmtDtls/TxAmt` and `CcyXchg` | `amountDetails.transactionAmount` |\n| `Chrgs/Rcrd` (`Amt`, `Agt`) | `charges` (`amount`, `currency`, `agent`) |\n| `RltdPties/DbtrAcct/Id` | `debtorAccount` |\n| `RltdPties/CdtrAcct/Id` | `creditorAccount` |\n| `RltdAgts/InstgAgt` | `instructingAgent` |\n| `RltdAgts/InstdAgt` | `instructedAgent` |\n| `RltdAgts/DbtrAgt` | `debtorAgent` |\n| `RltdAgts/CdtrAgt` | `creditorAgent` |\n| `RltdAgts/IntrmyAgt1` | `intermediaryAgent1` |\n| `RltdAgts/IntrmyAgt2` | `intermediaryAgent2` |\n| `RltdDts/AccptncDtTm` | `acceptanceDateTime` |\n| `RltdDts/IntrBkSttlmDt` | `interbankSettlementDate` |\n\nAvailable only here, with no camt.054 counterpart: `statusSource`, `acceptedAt`, `updatedAt`, `finalStatusAt`, `rejectionReason`, `pendingReason`, `pendingAgeSeconds`, `destinationAmount`, `sourceCountry`, `destinationCountry`, `direction`, and the charge record's `type`, `bearer` and `creditDebitIndicator`. Note that camt.054 carries the status code but no status reason, so a rejected or pending payment has a reason here and none in the file.\n\n`direction`, `creditDebitIndicator` and `bankTransactionCode.family` are three equivalent views of the same role and never disagree: an outbound payment is `DBIT` with family `IRCT`, an inbound payment is `CRDT` with family `RRCT`.\n\n`acceptedAt` is the instant Nexus recorded the acceptance: it assigns the Nexus Day, drives the date filters and starts pending age. `acceptanceDateTime` is the acceptance timestamp set by the Source PSP, copied from the pacs.008 as in camt.054.\n\nAgents are identified as in camt.054: by BIC, LEI or clearing-system member ID, with `scheme` naming the form and `id` carrying the value.\n\nBoth channels carry the debtor and creditor account identifiers copied from the pacs.008, for reconciliation. Neither carries names, addresses, proxy values (mobile number, email address or national ID) or remittance information. Account identifiers are not query filters and must not be logged.\n\nA logical query is its first request plus all valid cursor continuations. Continue using only cursor; the cursor inherits the validated dates, page size, filters and snapshot. A valid continuation remains permitted after the published new-query allowance is exhausted, including across midnight, until the cursor expires. A new first-request retry or an expired-cursor restart is a new logical query.\n\nHTTP 429 identifies rate, concurrency, daily-allowance or duplicate-query rejection and always supplies Retry-After. A range above 31 inclusive Nexus Days returns 400 RANGE_TOO_WIDE. Exceeding the published query-cost or total-result guards returns 422 QUERY_TOO_LARGE or RESULT_TOO_LARGE; narrow the range or add filters, never accept a silently truncated result. A result larger than one page is not an error.\n\nPagination example: start with fromDate=20260916, toDate=20260916, status=PDNG and pageSize=2. The firstPage response contains two records and nextCursor. Request the next page with that cursor alone; do not repeat pageSize, dates or status. The lastPage response contains the remaining record and omits both nextCursor and cursorExpiresAt. All pages retain the same dataAsOf and evaluatedAt. Example cursor values and expiry are illustrative, not published production lifetimes.", "x-query-modes": ["fromDate and toDate with optional status, other supported filters and pageSize", "cursor only; inherits original dates, filters, page size and snapshot"], "x-query-schema": {"$ref": "#/components/schemas/OperationalQuery"}, "x-codeSamples": [ {"lang": "HTTP", "label": "First page (pageSize=2)", "source": "GET /v1/operational-transactions?fromDate=20260916&toDate=20260916&status=PDNG&pageSize=2\nAccept: application/json\nAuthorization: Bearer "}, {"lang": "HTTP", "label": "Next page (cursor only)", "source": "GET /v1/operational-transactions?cursor=c-example-ipso-page-2\nAccept: application/json\nAuthorization: Bearer "} ], "x-usage-limits": {"newQueryRate": {"limit": 5, "windowSeconds": 60, "unit": "logical-queries", "window": "rolling"}, "identicalQueryCooldownSeconds": 1800, "concurrentRequests": 5, "dailyAllowance": {"limit": 50, "unit": "logical-queries"}, "maxInclusiveNexusDays": 31, "historyMonths": 13, "maxPageSize": 2500, "cursorContinuation": {"dailyUnits": 0, "newQueryRateUnits": 0, "identicalQueryCooldownApplies": false, "concurrencyApplies": true}}, "security": [{"nexusOAuth": ["operations.transactions.read"], "mutualTLS": []}], "parameters": [ {"$ref": "#/components/parameters/FromDate"}, {"$ref": "#/components/parameters/ToDate"}, {"$ref": "#/components/parameters/SendingIpso"}, {"$ref": "#/components/parameters/ReceivingIpso"}, {"$ref": "#/components/parameters/Direction"}, {"$ref": "#/components/parameters/PspId"}, {"$ref": "#/components/parameters/Status"}, {"$ref": "#/components/parameters/StatusSource"}, {"$ref": "#/components/parameters/PendingAgeBucket"}, {"$ref": "#/components/parameters/PageSize"}, {"$ref": "#/components/parameters/Cursor"}, {"$ref": "#/components/parameters/SignatureInputBodyless"}, {"$ref": "#/components/parameters/Signature"} ], "responses": { "200": { "description": "Scoped operational page of at most the requested pageSize, with an absolute maximum of 2,500 records. Empty items means no authorised match, not a failed source query. Use nextCursor for additional pages of the same logical query; both cursor fields are absent on the final page.", "headers": {"Cache-Control": {"$ref": "#/components/headers/NoStore"}, "Signature-Input": {"$ref": "#/components/headers/ResponseSignatureInput"}, "Signature": {"$ref": "#/components/headers/ResponseSignature"}, "Content-Digest": {"$ref": "#/components/headers/ResponseContentDigest"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TransactionPage"}, "examples": { "firstPage": { "summary": "First page of pending transactions, pageSize=2", "description": "Response to the first-page request sample. The cursor and its ten-minute example expiry are illustrative; production cursor lifetime remains a publication gate.", "value": {"authoritative": false, "items": [ {"uetr": "550e8400-e29b-41d4-a716-446655440000", "status": "PDNG", "statusSource": "NEXUS", "acceptedAt": "2026-09-16T08:00:00Z", "updatedAt": "2026-09-16T08:00:01Z", "pendingReason": {"code": "UNDER_INVESTIGATION", "description": "The settlement timer expired and the status enquiry cadence is running."}, "acceptanceDateTime": "2026-09-16T07:59:58Z", "entryAmount": {"amount": "1000.00", "currency": "MYR"}, "creditDebitIndicator": "DBIT", "bankTransactionCode": {"domain": "PMNT", "family": "IRCT", "subFamily": "XBCT"}, "references": {"messageId": "20260916NXPS081AB123456SBININBBXXXX", "instructionId": "BANK-A-INSTR-77451", "endToEndId": "INV-2026-04471", "uetr": "550e8400-e29b-41d4-a716-446655440000", "transactionId": "20260916NXPS081AB123456SBININBBXXXX", "clearingSystemReference": "NEXUS-CLR-20260916-0042"}, "amountDetails": {"instructedAmount": {"amount": "1000.00", "currency": "MYR"}, "currencyExchange": {"sourceCurrency": "MYR", "targetCurrency": "SGD", "exchangeRate": "0.32000000"}, "transactionAmount": {"amount": "1000.00", "currency": "MYR", "currencyExchange": {"sourceCurrency": "MYR", "targetCurrency": "SGD", "exchangeRate": "0.32000000"}}}, "charges": [{"amount": "2.50", "currency": "MYR", "creditDebitIndicator": "DBIT", "type": "SPSP", "bearer": "DEBT", "agent": {"scheme": "BIC", "id": "BANKMYKLAXX"}}, {"amount": "1.00", "currency": "SGD", "creditDebitIndicator": "DBIT", "type": "DPSP", "bearer": "DEBT", "agent": {"scheme": "BIC", "id": "BANKSGSGAXX"}}], "debtorAccount": {"scheme": "OTHER", "id": "5140123456789"}, "creditorAccount": {"scheme": "OTHER", "id": "0123456789"}, "instructingAgent": {"scheme": "BIC", "id": "BANKMYKLAXX"}, "instructedAgent": {"scheme": "BIC", "id": "SAPAMYKLXXX"}, "debtorAgent": {"scheme": "BIC", "id": "BANKMYKLAXX"}, "creditorAgent": {"scheme": "BIC", "id": "BANKSGSGAXX"}, "intermediaryAgent1": {"scheme": "BIC", "id": "SAPAMYKLXXX"}, "intermediaryAgent2": {"scheme": "BIC", "id": "SAPASGSGXXX"}, "interbankSettlementDate": "2026-09-16", "direction": "outbound", "sourceCountry": "MY", "destinationCountry": "SG", "destinationAmount": {"amount": "320.00", "currency": "SGD"}, "pendingAgeSeconds": 64860}, {"uetr": "660e8400-e29b-41d4-a716-446655440001", "status": "PDNG", "statusSource": "NEXUS", "acceptedAt": "2026-09-16T09:00:00Z", "updatedAt": "2026-09-16T09:00:01Z", "pendingReason": {"code": "DESTINATION_PROCESSING", "description": "The destination IPSO reported the payment as still in progress.", "destinationReasonCode": "AB07"}, "acceptanceDateTime": "2026-09-16T08:59:58Z", "entryAmount": {"amount": "2000.00", "currency": "MYR"}, "creditDebitIndicator": "DBIT", "bankTransactionCode": {"domain": "PMNT", "family": "IRCT", "subFamily": "XBCT"}, "references": {"messageId": "20260916NXPS081AB123456SBININBBXXXX", "instructionId": "BANK-A-INSTR-77451", "endToEndId": "INV-2026-04472", "uetr": "660e8400-e29b-41d4-a716-446655440001", "transactionId": "20260916NXPS081AB123456SBININBBXXXX", "clearingSystemReference": "NEXUS-CLR-20260916-0043"}, "amountDetails": {"instructedAmount": {"amount": "2000.00", "currency": "MYR"}, "currencyExchange": {"sourceCurrency": "MYR", "targetCurrency": "SGD", "exchangeRate": "0.32000000"}, "transactionAmount": {"amount": "2000.00", "currency": "MYR", "currencyExchange": {"sourceCurrency": "MYR", "targetCurrency": "SGD", "exchangeRate": "0.32000000"}}}, "charges": [{"amount": "2.50", "currency": "MYR", "creditDebitIndicator": "DBIT", "type": "SPSP", "bearer": "DEBT", "agent": {"scheme": "BIC", "id": "BANKMYKLAXX"}}, {"amount": "1.00", "currency": "SGD", "creditDebitIndicator": "DBIT", "type": "DPSP", "bearer": "DEBT", "agent": {"scheme": "CLEARING_MEMBER_ID", "id": "1234", "clearingSystemCode": "SGIBG"}}], "debtorAccount": {"scheme": "OTHER", "id": "5140987654321"}, "creditorAccount": {"scheme": "OTHER", "id": "0987654321"}, "instructingAgent": {"scheme": "BIC", "id": "BANKMYKLAXX"}, "instructedAgent": {"scheme": "BIC", "id": "SAPAMYKLXXX"}, "debtorAgent": {"scheme": "BIC", "id": "BANKMYKLAXX"}, "creditorAgent": {"scheme": "CLEARING_MEMBER_ID", "id": "1234", "clearingSystemCode": "SGIBG"}, "intermediaryAgent1": {"scheme": "BIC", "id": "SAPAMYKLXXX"}, "intermediaryAgent2": {"scheme": "LEI", "id": "9845001EXAMPLE000017"}, "interbankSettlementDate": "2026-09-16", "direction": "outbound", "sourceCountry": "MY", "destinationCountry": "SG", "destinationAmount": {"amount": "640.00", "currency": "SGD"}, "pendingAgeSeconds": 61260} ], "returnedCount": 2, "dataAsOf": "2026-09-17T02:00:00Z", "evaluatedAt": "2026-09-17T02:01:00Z", "dataQuality": "complete", "nextCursor": "c-example-ipso-page-2", "cursorExpiresAt": "2026-09-17T02:11:00Z"} }, "lastPage": { "summary": "Final page of the same logical query", "description": "Response to cursor=c-example-ipso-page-2 only. The original pageSize=2, dates, status and snapshot are inherited; one record remains, with no further cursor.", "value": {"authoritative": false, "items": [ {"uetr": "770e8400-e29b-41d4-a716-446655440002", "status": "PDNG", "statusSource": "NEXUS", "acceptedAt": "2026-09-16T10:00:00Z", "updatedAt": "2026-09-16T10:00:01Z", "acceptanceDateTime": "2026-09-16T09:59:58Z", "entryAmount": {"amount": "500.00", "currency": "MYR"}, "creditDebitIndicator": "DBIT", "bankTransactionCode": {"domain": "PMNT", "family": "IRCT", "subFamily": "XBCT"}, "references": {"messageId": "20260916NXPS081AB123456SBININBBXXXX", "instructionId": "BANK-A-INSTR-77451", "endToEndId": "INV-2026-04473", "uetr": "770e8400-e29b-41d4-a716-446655440002", "transactionId": "20260916NXPS081AB123456SBININBBXXXX", "clearingSystemReference": "NEXUS-CLR-20260916-0044"}, "amountDetails": {"instructedAmount": {"amount": "500.00", "currency": "MYR"}, "currencyExchange": {"sourceCurrency": "MYR", "targetCurrency": "SGD", "exchangeRate": "0.32000000"}, "transactionAmount": {"amount": "500.00", "currency": "MYR", "currencyExchange": {"sourceCurrency": "MYR", "targetCurrency": "SGD", "exchangeRate": "0.32000000"}}}, "charges": [{"amount": "2.50", "currency": "MYR", "creditDebitIndicator": "DBIT", "type": "SPSP", "bearer": "DEBT", "agent": {"scheme": "BIC", "id": "BANKMYKLAXX"}}, {"amount": "1.00", "currency": "SGD", "creditDebitIndicator": "DBIT", "type": "DPSP", "bearer": "DEBT", "agent": {"scheme": "BIC", "id": "BANKSGSGAXX"}}], "debtorAccount": {"scheme": "OTHER", "id": "5140555000111"}, "creditorAccount": {"scheme": "OTHER", "id": "0555000111"}, "instructingAgent": {"scheme": "BIC", "id": "BANKMYKLAXX"}, "instructedAgent": {"scheme": "BIC", "id": "SAPAMYKLXXX"}, "debtorAgent": {"scheme": "BIC", "id": "BANKMYKLAXX"}, "creditorAgent": {"scheme": "BIC", "id": "BANKSGSGAXX"}, "intermediaryAgent1": {"scheme": "BIC", "id": "SAPAMYKLXXX"}, "intermediaryAgent2": {"scheme": "BIC", "id": "SAPASGSGXXX"}, "interbankSettlementDate": "2026-09-16", "direction": "outbound", "sourceCountry": "MY", "destinationCountry": "SG", "destinationAmount": {"amount": "160.00", "currency": "SGD"}, "pendingAgeSeconds": 57660} ], "returnedCount": 1, "dataAsOf": "2026-09-17T02:00:00Z", "evaluatedAt": "2026-09-17T02:01:00Z", "dataQuality": "complete"} } }}} }, "400": {"$ref": "#/components/responses/QueryBadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/QueryGuardrailExceeded"}, "429": {"$ref": "#/components/responses/FeedThrottled"}, "500": {"$ref": "#/components/responses/InternalError"}, "503": {"$ref": "#/components/responses/Unavailable"}, "default": {"$ref": "#/components/responses/PerimeterError"} } } }, "/v1/track-and-trace/{uetr}": { "get": { "tags": ["TrackAndTrace"], "operationId": "trackAndTrace", "summary": "Track and trace a payment", "x-release": "Release 1", "servers": [{"url": "https://{environment}.payments.nexus.net", "description": "Track and Trace is served on the Payment Processing host, not the Operations reporting host, because it reads live payment records and uses payment API authentication.", "variables": {"environment": {"default": "prod", "enum": ["pat", "prod"], "description": "Deployment environment subdomain."}}}], "description": "Return the current status of a single transaction by UETR, to help the IPSO answer a customer enquiry. Use it when a customer asks about a payment and the IPSO has sent the pacs.008 but has not received the pacs.002; where the IPSO already holds the pacs.002 it answers from its own records. Exactly one UETR per request: no bulk or list queries. The published request rate is shared across the Track and Trace screen and API callers, and exceeding it returns 429 RATE_LIMIT_EXCEEDED with Retry-After. This is not a polling service or a way to reconstruct the Operational Data Feed.\n\nUnlike the other operations in this document, Track and Trace uses the Payment Processing authentication, host and network path rather than the separate Operations reporting ones: a payment-realm certificate-bound access token, mutual TLS, and an RFC 9421 message signature produced with the IPSO's payment signing key pair rather than its Operations signing key pair. Nexus signs the 200 response, and the IPSO verifies it before use. Operations reporting tokens are not accepted.\n\nThe enquiry does not update the IPSO's records and does not replace pacs.028. Where a pacs.002 does not arrive, the IPSO must still send a pacs.028 and process the resulting pacs.002 to close the payment in its own journal. The IPSO is identified from its credentials and no participant identifier is passed in the request; a PSP enquiry goes to its IPSO, which queries Nexus. Nexus holds only the UETR, so the IPSO maps its own domestic reference to it.", "x-usage-limits": {"rate": {"limit": 60, "windowSeconds": 60, "unit": "requests", "window": "rolling"}, "sharedChannels": ["screen", "api"], "uetrsPerRequest": 1, "historyMonths": 13}, "security": [{"paymentsOAuth": ["trackandtrace.read"], "mutualTLS": []}], "parameters": [ {"name": "uetr", "in": "path", "required": true, "description": "Exactly one UUID v4, identifying the single transaction. No bulk or list form of this operation exists.", "schema": {"$ref": "#/components/schemas/Uetr"}, "example": "550e8400-e29b-41d4-a716-446655440000"}, {"$ref": "#/components/parameters/SignatureInputBodyless"}, {"$ref": "#/components/parameters/Signature"} ], "responses": { "200": {"description": "Latest known status, with the rejection or pending reason where applicable and key event timestamps. For customer enquiries, not journal updates. If pacs.002 is missing, send pacs.028 and process the resulting pacs.002 to update the IPSO journal.", "headers": {"Cache-Control": {"$ref": "#/components/headers/NoStore"}, "Signature-Input": {"$ref": "#/components/headers/ResponseSignatureInput"}, "Signature": {"$ref": "#/components/headers/ResponseSignature"}, "Content-Digest": {"$ref": "#/components/headers/ResponseContentDigest"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrackAndTraceResult"}, "example": {"authoritative": false, "uetr": "550e8400-e29b-41d4-a716-446655440000", "status": "PDNG", "statusSource": "NEXUS", "acceptedAt": "2026-09-17T02:00:00Z", "updatedAt": "2026-09-17T02:00:01Z", "dataAsOf": "2026-09-17T02:00:03Z", "dataQuality": "complete", "pendingReason": {"code": "AWAITING_DESTINATION_RESPONSE", "description": "The payment was dispatched to the destination IPSO and no status has been returned yet."}}}}}, "400": {"$ref": "#/components/responses/BadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/TransactionMissing"}, "429": {"$ref": "#/components/responses/RateLimited"}, "500": {"$ref": "#/components/responses/InternalError"}, "503": {"$ref": "#/components/responses/Unavailable"}, "default": {"$ref": "#/components/responses/PerimeterError"} } } }, "/v1/service-requests": { "post": { "tags": ["ServiceRequests"], "operationId": "submitServiceRequest", "summary": "Create a ServiceNow ticket", "x-command-type": "SubmitServiceRequest", "x-release": "Release 2", "x-catalog-profiles": [ {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "TECHNICAL_SUPPORT", "payloadVersion": "1.0", "subCatalogItem": "Request for Technical support or enquiries", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "PARTICIPANT_SUPPORT", "payloadVersion": "1.0", "subCatalogItem": "Raise Participant General Support Request/ Enquires", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "MTLS_CERTIFICATE_EXPIRY", "payloadVersion": "1.0", "subCatalogItem": "mTLS Certificate Expiry Support Request", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "CONFIDENTIAL_DISCLOSURE_REQUEST", "payloadVersion": "1.0", "subCatalogItem": "Request Confidential Information Disclosure", "recipientType": "NGP", "fulfilmentOwner": "NGP"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "NEXUS_PORTAL_SUPPORT", "payloadVersion": "1.0", "subCatalogItem": "Request Nexus Portal and PAT Integration Support", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "REFERENCE_DATA_CHANGE", "payloadVersion": "1.0", "subCatalogItem": "Request Participant Reference Data Change", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "PAYMENT_RECALL", "payloadVersion": "1.0", "subCatalogItem": "Raise Payment Recall Request", "recipientType": "IPSO", "fulfilmentOwner": "Counterparty IPSO"}, {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "primaryCatalog": "Participant Support & Requests", "requestCode": "PAYMENT_INFORMATION_REQUEST", "payloadVersion": "1.0", "subCatalogItem": "Request Further Payment Information", "recipientType": "IPSO", "fulfilmentOwner": "Counterparty IPSO"}, {"category": "PARTICIPANT_MANAGEMENT", "primaryCatalog": "Participant Management", "requestCode": "IPSO_ONBOARDING_APPLICATION", "payloadVersion": "1.0", "subCatalogItem": "Submit IPSO Onboarding Application", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_MANAGEMENT", "primaryCatalog": "Participant Management", "requestCode": "PSP_ONBOARDING_APPLICATION", "payloadVersion": "1.0", "subCatalogItem": "Submit PSP Onboarding Application", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_MANAGEMENT", "primaryCatalog": "Participant Management", "requestCode": "SAP_ONBOARDING_APPLICATION", "payloadVersion": "1.0", "subCatalogItem": "Submit SAP Onboarding Application", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_MANAGEMENT", "primaryCatalog": "Participant Management", "requestCode": "PDO_ONBOARDING_APPLICATION", "payloadVersion": "1.0", "subCatalogItem": "Submit PDO Onboarding Application", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "PARTICIPANT_MANAGEMENT", "primaryCatalog": "Participant Management", "requestCode": "FXP_KYB_REQUEST", "payloadVersion": "1.0", "subCatalogItem": "Submit CBDDQ / FXP KYB Request", "recipientType": "FXP", "fulfilmentOwner": "Selected FXP"}, {"category": "PARTICIPANT_MANAGEMENT", "primaryCatalog": "Participant Management", "requestCode": "DIRECT_PARTICIPANT_WITHDRAWAL", "payloadVersion": "1.0", "subCatalogItem": "Request Direct Participant Withdrawal", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "primaryCatalog": "Incident & Availability Management", "requestCode": "TECHNICAL_INCIDENT", "payloadVersion": "1.0", "subCatalogItem": "Report a Technical incident", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "primaryCatalog": "Incident & Availability Management", "requestCode": "SECURITY_INCIDENT", "payloadVersion": "1.0", "subCatalogItem": "Report a security Incident", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "primaryCatalog": "Incident & Availability Management", "requestCode": "PARTICIPANT_OUTAGE", "payloadVersion": "1.0", "subCatalogItem": "Report unplanned Current Participant Outage", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "primaryCatalog": "Incident & Availability Management", "requestCode": "PLANNED_DOWNTIME", "payloadVersion": "1.0", "subCatalogItem": "Notify Planned IPSO Downtime or Recovery", "recipientType": "NGO", "fulfilmentOwner": "NGO"}, {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "primaryCatalog": "Dispute & Resolution Management", "requestCode": "DISPUTE_TRANSACTION_PROCESSING", "payloadVersion": "1.0", "subCatalogItem": "Raise Formal Dispute \u2014 Transaction Processing", "recipientType": "IPSO", "fulfilmentOwner": "Responding IPSO"}, {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "primaryCatalog": "Dispute & Resolution Management", "requestCode": "DISPUTE_FRAUD_OR_SCAM", "payloadVersion": "1.0", "subCatalogItem": "Raise Formal Dispute \u2014 Fraud or Scam", "recipientType": "IPSO", "fulfilmentOwner": "Responding IPSO"}, {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "primaryCatalog": "Dispute & Resolution Management", "requestCode": "DISPUTE_SCHEME_NON_COMPLIANCE", "payloadVersion": "1.0", "subCatalogItem": "Raise Formal Dispute \u2014 Scheme Non-Compliance", "recipientType": "IPSO", "fulfilmentOwner": "Responding IPSO"}, {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "primaryCatalog": "Dispute & Resolution Management", "requestCode": "RECONCILIATION_DISCREPANCY", "payloadVersion": "1.0", "subCatalogItem": "Report Reconciliation Discrepancy", "recipientType": "IPSO", "fulfilmentOwner": "Responding IPSO"}, {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "primaryCatalog": "Dispute & Resolution Management", "requestCode": "SCHEME_FEE_QUERY", "payloadVersion": "1.0", "subCatalogItem": "Raise Scheme Fee Calculation or Report Query", "recipientType": "NGP", "fulfilmentOwner": "NGP"}, {"category": "FEEDBACK_AND_COMPLAINT", "primaryCatalog": "Feedback & Complaint", "requestCode": "FEEDBACK_AND_COMPLAINT", "payloadVersion": "1.0", "subCatalogItem": "Raise a Feedback and Complaint to Nexus", "recipientType": "NGO", "fulfilmentOwner": "NGO"} ], "x-catalog-profile-notes": "Each profile binds one request code to its primary catalog, sub-catalog item name, category, recipient type and fulfilment owner. The binding is approved as a whole: a submission must match a profile exactly, and no part of it may be substituted at request time. Catalog items sourced by NGO, NGP, FXP or Nexus automation are out of scope for this IPSO-facing API.", "description": "Create a new ServiceNow ticket through the NGO-operated intake, addressed to NGO, NGP, a counterparty IPSO or a selected FXP depending on the ticket type. Select the ticket type with requestCode and payloadVersion. Each code fixes its recipient type; an unsupported code/version, mismatched recipient type or unknown payload field is 400 INVALID_REQUEST. payload is a governed type-specific JSON object, not arbitrary ServiceNow fields.\n\nUse the dedicated create scope with the existing Operations OAuth, certificate-bound mTLS and IPsec controls, and sign the request with RFC 9421 and a Content-Digest over the exact JSON body bytes, using the IPSO's Operations signing key pair. The 202 response is not signed. Sender identity and environment come from credentials. A counterparty IPSO is identified by its registered BIC.CurrencyCode identifier, must differ from the sender and must be eligible to receive that request type from the sender in that environment; an FXP is identified by its registered scheme-assigned identifier. Missing scope or type permission and an ineligible recipient are a non-disclosing 403.\n\nSend application/json with a required Idempotency-Key. No attachments, file references, customer PII, secrets, batches or specialised workflow actions. Body size is at most 64 KiB.\n\nAccepting a request never performs the underlying business action. A recall does not recall a payment, a lifecycle request does not suspend or terminate a participant, a challenge does not stay a scheme decision, and an onboarding application does not onboard. Each is routed to the governed process that owns the outcome.\n\n202 means the validated submission, immutable receipt and routing work were durably committed, not that the ServiceNow ticket already exists, the responding IPSO received the dispute or fulfilment succeeded. Exact retries return the same receipt; changed content under the same key returns 409. Reuse the key after an uncertain timeout within the published replay window. Downstream retries are deduplicated by requestId.\n\nTrack progress through the existing authorised Service Desk channel using requestId; once created, the ticket reference is linked there. This API adds no polling, update, upload or callback endpoint and returns no Location URL. ServiceNow unavailability after acceptance is handled by monitored retry/recovery, not by asking the IPSO to create a second ticket.", "security": [{"nexusOAuth": ["operations.service-requests.create"], "mutualTLS": []}], "x-request-limits": {"maxBodyBytes": 65536, "requestsPerSubmission": 1, "attachmentsAllowed": false, "quotaAggregation": "Submitting IPSO and authenticated environment", "quotaPublicationRequired": true}, "parameters": [{"$ref": "#/components/parameters/ServiceRequestIdempotencyKey"}, {"$ref": "#/components/parameters/SignatureInputWithBody"}, {"$ref": "#/components/parameters/Signature"}, {"$ref": "#/components/parameters/ContentDigest"}], "requestBody": { "required": true, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ServiceRequestSubmission"}, "examples": { "generalSupport": {"summary": "General support request to NGO", "value": {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "requestCode": "PARTICIPANT_SUPPORT", "payloadVersion": "1.0", "recipient": {"type": "NGO"}, "subject": "Clarification of the non-urgent support procedure", "description": "Please confirm the approved escalation route for non-urgent participant support.", "payload": {"clientReference": "IPSO-SUPPORT-20261002-001"}}}, "technicalIncident": {"summary": "Technical incident report to NGO", "value": {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "requestCode": "TECHNICAL_INCIDENT", "payloadVersion": "1.0", "recipient": {"type": "NGO"}, "subject": "Elevated pacs.008 timeouts on outbound corridor MY-SG", "description": "Since 09:40 SGT approximately 15% of outbound payments to SG receive no pacs.002 within the expected window.", "payload": {"clientReference": "IPSO-INC-20261002-004", "detectedAt": "2026-10-02T01:40:00Z"}}}, "participantOutage": {"summary": "Unplanned outage of the submitting IPSO", "description": "The Payment Processing API admi.004 notification is the primary channel for this item; this intake is the alternative used when the payment flow is unavailable.", "value": {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "requestCode": "PARTICIPANT_OUTAGE", "payloadVersion": "1.0", "recipient": {"type": "NGO"}, "subject": "Unplanned outage of the IPSO gateway", "description": "The IPSO gateway became unavailable at 02:10 SGT; inbound and outbound Nexus traffic is currently failing and recovery is not yet confirmed.", "payload": {"clientReference": "IPSO-OUT-20261002-002", "outageStartedAt": "2026-10-01T18:10:00Z"}}}, "plannedDowntime": {"summary": "Planned downtime notification to NGO", "value": {"category": "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "requestCode": "PLANNED_DOWNTIME", "payloadVersion": "1.0", "recipient": {"type": "NGO"}, "subject": "Scheduled gateway maintenance", "description": "Planned maintenance of the IPSO gateway; inbound and outbound Nexus traffic will be unavailable during the window.", "payload": {"clientReference": "IPSO-MAINT-20261010-001", "plannedStartAt": "2026-10-10T18:00:00Z", "plannedEndAt": "2026-10-10T20:00:00Z"}}}, "paymentRecall": {"summary": "Payment recall request to the counterparty IPSO", "description": "Acceptance routes the request to the counterparty; it does not recall, cancel or reverse the payment.", "value": {"category": "PARTICIPANT_SUPPORT_AND_REQUESTS", "requestCode": "PAYMENT_RECALL", "payloadVersion": "1.0", "recipient": {"type": "IPSO", "ipsoId": "MASSGSGSGSG.SGD"}, "subject": "Recall request for a duplicated outbound payment", "description": "The referenced payment was instructed twice by the originating PSP. We request the return of the second payment in full.", "payload": {"clientReference": "IPSO-RCL-20261002-001", "uetr": "550e8400-e29b-41d4-a716-446655440000"}}}, "formalDispute": {"summary": "Formal transaction-processing dispute with the responding IPSO", "description": "The authenticated sender must be a different IPSO that is eligible to raise disputes with this registered responding IPSO.", "value": {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "requestCode": "DISPUTE_TRANSACTION_PROCESSING", "payloadVersion": "1.0", "recipient": {"type": "IPSO", "ipsoId": "MASSGSGSGSG.SGD"}, "subject": "Unresolved transaction-processing dispute", "description": "Bilateral resolution attempts since 2026-09-20 have not resolved the processing outcome of the referenced payment.", "payload": {"clientReference": "IPSO-DSP-20261002-001", "uetr": "550e8400-e29b-41d4-a716-446655440000"}}}, "schemeFeeQuery": {"summary": "Scheme Fee calculation query to NGP", "value": {"category": "DISPUTE_AND_RESOLUTION_MANAGEMENT", "requestCode": "SCHEME_FEE_QUERY", "payloadVersion": "1.0", "recipient": {"type": "NGP"}, "subject": "Query on the September Scheme Fee calculation", "description": "The transaction volume underlying the September Scheme Fee calculation does not reconcile with our own records. Please review the supporting report data.", "payload": {"clientReference": "IPSO-FEE-20261002-001", "billingPeriod": "2026-09"}}}, "pspOnboarding": {"summary": "PSP onboarding application to NGO", "value": {"category": "PARTICIPANT_MANAGEMENT", "requestCode": "PSP_ONBOARDING_APPLICATION", "payloadVersion": "1.0", "recipient": {"type": "NGO"}, "subject": "Onboarding application for a sponsored PSP", "description": "We sponsor this PSP and request that its onboarding case be opened. Due-diligence evidence will follow through the authorised onboarding channel.", "payload": {"clientReference": "IPSO-ONB-20261002-001", "applicantType": "PSP", "applicantReference": "PSP-MY-001"}}}, "feedbackAndComplaint": {"summary": "Feedback or complaint to NGO", "value": {"category": "FEEDBACK_AND_COMPLAINT", "requestCode": "FEEDBACK_AND_COMPLAINT", "payloadVersion": "1.0", "recipient": {"type": "NGO"}, "subject": "Feedback on the reporting retrieval experience", "description": "Report retrieval during the first hour after publication is slower than expected. We would like this reviewed and the outcome documented.", "payload": {"clientReference": "IPSO-FBK-20261002-001"}}} } }} }, "responses": { "202": {"description": "Durable NGO acceptance receipt, also returned unchanged for an authorised exact replay. Acceptance is not a ServiceNow creation, delivery or fulfilment acknowledgement.", "headers": {"Cache-Control": {"$ref": "#/components/headers/NoStore"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ServiceRequestReceipt"}, "example": {"requestId": "8b7088e0-2f5c-4cb8-9ec9-6c30b38a42d1", "status": "ACCEPTED", "acceptedAt": "2026-10-02T08:15:00Z"}}}}, "400": {"$ref": "#/components/responses/ServiceRequestBadRequest"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/ServiceRequestForbidden"}, "409": {"$ref": "#/components/responses/ServiceRequestIdempotencyConflict"}, "413": {"description": "Native HTTP rejection: JSON request body exceeds 65536 bytes. No acceptance or new idempotency reservation; no Nexus JSON error-body guarantee. Reduce the request; do not split it into unapproved batch or attachment submissions."}, "415": {"description": "Native HTTP rejection: only UTF-8 application/json with no content encoding other than identity is supported. Multipart, binary and compressed bodies are not accepted. No Nexus JSON error-body guarantee."}, "429": {"$ref": "#/components/responses/ServiceRequestThrottled"}, "500": {"$ref": "#/components/responses/ServiceRequestInternalError"}, "503": {"$ref": "#/components/responses/ServiceRequestUnavailable"}, "default": {"$ref": "#/components/responses/PerimeterError"} } } } }, "components": { "securitySchemes": { "nexusOAuth": {"type": "oauth2", "description": "Operations client-credentials access token. Validate exact approved issuer, Operations audience, signature/JWKS, expiry, scopes, active IPSO and environment. Present the Operations certificate at token issuance and verify its SHA-256 thumbprint against cnf.x5t#S256 on every call. Aggregate quotas by the trusted IPSO identity across credentials; human sessions never grant machine scopes. Never log tokens or derive identity from request headers. Every request additionally carries an RFC 9421 message signature (Signature-Input, Signature, and Content-Digest when it has a body) produced with the IPSO's Operations signing key pair.", "flows": {"clientCredentials": {"tokenUrl": "https://auth.nexus.net/realms/nexus-operations/protocol/openid-connect/token", "scopes": {"Operations.reports": "Read IPSO daily report manifests and download links", "operations.transactions.read": "Read the IPSO operational transaction dataset", "operations.service-requests.create": "Create supported ServiceNow tickets addressed to NGO, NGP, an authorised counterparty IPSO or a selected FXP; grants no reporting, fulfilment or approval rights"}}}}, "paymentsOAuth": {"type": "oauth2", "description": "Payment Processing client-credentials access token, used only by Track and Trace. It is issued by the payment authorization server, not the Operations one, and Operations reporting tokens are not accepted on this operation and vice versa. Present the payment client certificate at token issuance and verify its SHA-256 thumbprint against cnf.x5t#S256 on every call. Every request additionally carries an RFC 9421 message signature (Signature-Input, Signature) produced with the IPSO's payment signing key pair, not its Operations signing key pair. The scope name is a publication gate.", "flows": {"clientCredentials": {"tokenUrl": "https://auth.nexus.net/realms/nexus/protocol/openid-connect/token", "scopes": {"trackandtrace.read": "Read the latest known state of a single transaction the IPSO is party to, by UETR"}}}}, "mutualTLS": {"type": "mutualTLS", "description": "Required together with OAuth, over the separately established IPsec connection: the Operations connection for the reporting and service-request operations, and the Payment Processing connection for Track and Trace. The live client certificate must match the token's RFC 8705 cnf.x5t#S256 binding. TLS failure may produce no HTTP response."} }, "headers": { "NoStore": {"description": "Prevent HTTP caching of participant responses and signed URLs. Authorised processing and retention of retrieved business data in IPSO systems is governed separately.", "schema": {"type": "string", "const": "no-store"}}, "RetryAfter": {"description": "Mandatory on every policy 429 and on 409 REPORT_NOT_READY. Positive delay-seconds, rounded up to the earliest permitted retry; where several controls block the request, the longest known blocking delay is returned. A concurrency-only rejection does not reserve a slot. Honour this value as a minimum before bounded exponential backoff with jitter.", "required": true, "schema": {"type": "integer", "minimum": 1}, "example": 60}, "ResponseSignatureInput": {"description": "RFC 9421 signature metadata for a GET response, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). Signed by Nexus with its signing private key for this API path (the Nexus Operations signing key on the Operations host). Covered components: `\"@status\" \"content-type\" \"content-digest\"` on 200, or `\"@status\" \"etag\"` on 304, followed in both cases by the request-bound components `\"@method\";req \"@path\";req \"@query\";req`, which tie the response to the resource that was requested. Same `created`, `expires`, `keyid`, `alg` and `tag` rules as requests. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.", "required": true, "schema": {"type": "string", "maxLength": 512, "pattern": "^nexus=\\(\"@status\" (\"content-type\" \"content-digest\"|\"etag\") \"@method\";req \"@path\";req \"@query\";req\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}, "example": "nexus=(\"@status\" \"content-type\" \"content-digest\" \"@method\";req \"@path\";req \"@query\";req);created=1786339201;expires=1786339501;keyid=\"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\""}, "ResponseSignature": {"description": "RFC 9421 response signature: one dictionary member labelled `nexus` holding the standard base64 `rsa-pss-sha512` signature produced by the responding server over the signature base declared in the response `Signature-Input`. Verified by the client against the server's registered signing public key.", "required": true, "schema": {"type": "string", "minLength": 520, "maxLength": 1400, "pattern": "^nexus=:[A-Za-z0-9+/]+={0,2}:$"}, "example": "nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:"}, "ResponseContentDigest": {"description": "RFC 9530 SHA-512 digest of the exact response body bytes, covered by the response signature.", "required": true, "schema": {"type": "string", "pattern": "^sha-512=:[A-Za-z0-9+/]{86}==:$"}, "example": "sha-512=:lrQ9ipCrih8s4ITWLSvUXfJZ3l2z1suXuKukjNLHm/y+e/T7V3MDDjk1EXlx5yG7fusd5hRoTfwN1+c+4GptSA==:"} }, "parameters": { "SignatureInputBodyless": {"name": "Signature-Input", "in": "header", "required": true, "description": "RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled `nexus` whose covered components are exactly `\"@method\" \"@authority\" \"@path\" \"@query\"`, followed by `\"if-none-match\"` when that header is sent. `@query` is always covered; an empty query serialises as `?`, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: `created` and `expires` (Unix seconds; `expires` = `created` + 300; the receiver rejects `created` more than ±5 minutes from its clock or a signature past `expires`), `keyid` (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), `alg` (always `rsa-pss-sha512`) and `tag` (always `nexus-v1`). The signature parameters are signed through the `@signature-params` line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.", "schema": {"type": "string", "maxLength": 512, "pattern": "^nexus=\\(\"@method\" \"@authority\" \"@path\" \"@query\"( \"if-none-match\")?\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}, "example": "nexus=(\"@method\" \"@authority\" \"@path\" \"@query\");created=1786339201;expires=1786339501;keyid=\"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\""}, "SignatureInputWithBody": {"name": "Signature-Input", "in": "header", "required": true, "description": "RFC 9421 signature metadata for a request with a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled `nexus` whose covered components are exactly `\"@method\" \"@authority\" \"@path\" \"@query\" \"content-type\" \"content-digest\"`, so the body is bound to the signature through its `Content-Digest`. Signature parameters, emitted in this order: `created` and `expires` (Unix seconds; `expires` = `created` + 300; the receiver rejects `created` more than ±5 minutes from its clock or a signature past `expires`), `keyid` (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), `alg` (always `rsa-pss-sha512`) and `tag` (always `nexus-v1`). The signature parameters are signed through the `@signature-params` line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.", "schema": {"type": "string", "maxLength": 512, "pattern": "^nexus=\\(\"@method\" \"@authority\" \"@path\" \"@query\" \"content-type\" \"content-digest\"\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}, "example": "nexus=(\"@method\" \"@authority\" \"@path\" \"@query\" \"content-type\" \"content-digest\");created=1786339201;expires=1786339501;keyid=\"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\""}, "Signature": {"name": "Signature", "in": "header", "required": true, "description": "RFC 9421 signature value: one dictionary member labelled `nexus` holding an RFC 8941 byte sequence - the **standard base64** (not base64url) RSASSA-PSS signature using SHA-512 (`rsa-pss-sha512`), computed over the RFC 9421 signature base built from the components and parameters declared in `Signature-Input`. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from `keyid`. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005. The signing key depends on the API path: operations on the Operations host are signed with the IPSO's Operations signing key pair, and Track and Trace, which uses the Payment Processing security model, with the IPSO's payment signing key pair. A key registered for the other path does not verify and is rejected with AE005.", "schema": {"type": "string", "minLength": 520, "maxLength": 1400, "pattern": "^nexus=:[A-Za-z0-9+/]+={0,2}:$"}, "example": "nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:"}, "ContentDigest": {"name": "Content-Digest", "in": "header", "required": true, "description": "RFC 9530 digest of the exact request body bytes as sent: `sha-512=::`. Covered by the signature. The receiver recomputes the digest over the received bytes and rejects a mismatch with AE005 before verifying the signature. Only `sha-512` is accepted.", "schema": {"type": "string", "pattern": "^sha-512=:[A-Za-z0-9+/]{86}==:$"}, "example": "sha-512=:3Sd3sG3WdBHVvvBdDh960Fgte6DbbpV+0NCVwRGakd3zwCpydFQv5xs80UQg3u7JtC+mLXzHybSsjJUvN0Cf8g==:"}, "ServiceRequestIdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated UUID v4, used once per intended submission. Scope is authenticated submitting IPSO + environment + operation, never token, replica or recipient alone. Reuse exactly the same key and JSON body on network, 500, 502, 503 or 504 uncertainty within the published replay window; honour Retry-After where supplied. An exact replay returns the original 202 receipt without another business-allowance unit; a changed body (including recipient) is 409 IDEMPOTENCY_KEY_CONFLICT. Invalid requests create no new reservation. Concurrent duplicates must converge on one requestId. Never retry an uncertain accepted submission with a new key; resolve it through Service Desk after the replay window. Treat the key as opaque and do not log it raw.", "schema": {"type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}, "example": "bc689fb6-c2a0-4b9a-a3c7-41cc4be6ba0b"}, "ReportDate": {"name": "date", "in": "query", "required": true, "description": "Real YYYYMMDD Nexus date, UTC+08:00. Exactly one Nexus Day; repeated dates, arrays, ranges and other query parameters are rejected. Future dates are invalid, and a date outside the self-service retrieval window returns 410 REPORT_OUTSIDE_RETRIEVAL_WINDOW.", "schema": {"$ref": "#/components/schemas/ReportDate"}, "example": "20260916"}, "FromDate": {"name": "fromDate", "in": "query", "description": "Required with toDate on every first request, including status-filtered and pending-age queries; omitted only with cursor, which inherits the dates. Inclusive Nexus Day in YYYYMMDD, the same date format as the camt.054 date parameter and manifest nexusDay, at most 31 inclusive days within the retained history window. Missing, invalid or out-of-retention dates are 400 INVALID_REQUEST; an otherwise valid range over 31 days is 400 RANGE_TOO_WIDE.", "schema": {"$ref": "#/components/schemas/ReportDate"}, "example": "20260916"}, "ToDate": {"name": "toDate", "in": "query", "description": "Required with fromDate on every first request. Inclusive Nexus Day in YYYYMMDD, not before fromDate or after today's SGT date. The inclusive day count is date difference plus one. Set both dates to today to retrieve today's activity; there is no implicit date default. Cursor continuation inherits the original range; date-free first requests are never accepted.", "schema": {"$ref": "#/components/schemas/ReportDate"}, "example": "20260916"}, "SendingIpso": {"name": "sendingIpso", "in": "query", "description": "Sending IPS as a registered IPSOId, which combines the IPS BIC and its currency (BIC.CurrencyCode) and therefore identifies the sending IPS and the sending currency in one key. Must be inside the authenticated IPSO's authorised scope.", "schema": {"$ref": "#/components/schemas/IPSOId"}, "example": "MYBMMYKLXXX.MYR"}, "ReceivingIpso": {"name": "receivingIpso", "in": "query", "description": "Receiving IPS as a registered IPSOId, combining the IPS BIC and its currency (BIC.CurrencyCode) and therefore identifying the receiving IPS and the receiving currency in one key. Supply sendingIpso and receivingIpso together to select one directed corridor.", "schema": {"$ref": "#/components/schemas/IPSOId"}, "example": "MASSGSGSGSG.SGD"}, "Direction": {"name": "direction", "in": "query", "description": "Relative to the authenticated IPSO; omitted means both.", "schema": {"type": "string", "enum": ["inbound", "outbound"]}}, "PspId": {"name": "pspId", "in": "query", "description": "Own domestic PSP, matched exactly against the agent id whatever its scheme: a BIC, an LEI or a clearing-system member ID. Matches creditorAgent on an inbound payment, debtorAgent on an outbound one, and either domestic side when direction is omitted. Prefer retrieving once and splitting locally instead of a separate query per PSP.", "schema": {"type": "string", "minLength": 1, "maxLength": 35}}, "Status": {"name": "status", "in": "query", "description": "Optional current source-owned payment status, directly filtering transactions inside the required Nexus acceptance-date range. Omit to include all statuses unless another filter narrows them. A pendingAgeBucket intersects the population with current PDNG; a different status yields an empty eligible result.", "schema": {"$ref": "#/components/schemas/PaymentStatus"}, "example": "PDNG"}, "StatusSource": {"name": "statusSource", "in": "query", "description": "Who supplied the current payment status, not ingestion provenance.", "schema": {"$ref": "#/components/schemas/StatusSource"}}, "PendingAgeBucket": {"name": "pendingAgeBucket", "in": "query", "description": "Optional filter for current PDNG, intersected with the mandatory dates and every other supplied filter. Intervals measured from Nexus acceptance: [0,5m), [5m,1h), [1h,8h), [8h,30h), [30h,retention]. It implies PDNG when status is omitted; a non-PDNG status yields an empty eligible result. Valid for any permitted date range, including today; does not waive dates or create or imply a ticket.", "schema": {"type": "string", "enum": ["under_5m", "5m_to_1h", "1h_to_8h", "8h_to_30h", "overdue"]}}, "PageSize": {"name": "pageSize", "in": "query", "description": "First-page size from 1 to 2,500 records. Values above the maximum are 400 INVALID_REQUEST, never silently capped. Cursor pages inherit this size; pageSize cannot accompany cursor. The pagination examples request two records per page.", "schema": {"type": "integer", "minimum": 1, "maximum": 2500}, "example": 2}, "Cursor": {"name": "cursor", "in": "query", "description": "Opaque continuation; must be the only parameter. Binds IPSO/environment, original dates/filters/page size, ordering, snapshot, evaluation time and admitted logical query. An expired, invalid or cross-scope cursor is 400 INVALID_REQUEST, never a silent restart. Authorisation is rechecked on every continuation.", "schema": {"type": "string", "minLength": 1}, "example": "c-example-ipso-page-2"} }, "schemas": { "ServiceRequestCategory": {"type": "string", "enum": ["PARTICIPANT_SUPPORT_AND_REQUESTS", "PARTICIPANT_MANAGEMENT", "INCIDENT_AND_AVAILABILITY_MANAGEMENT", "DISPUTE_AND_RESOLUTION_MANAGEMENT", "FEEDBACK_AND_COMPLAINT"], "description": "Primary catalog grouping of the selected ticket type, grouping the service catalog into its five primary areas. Exactly one category applies to each requestCode, so the pair is fixed by the catalog and never chosen freely: a category that does not match the selected requestCode is 400 INVALID_REQUEST. It is a classification, not a routing instruction, and does not select a recipient, fulfilment group, priority or service level."}, "ServiceRequestCode": {"type": "string", "enum": ["TECHNICAL_SUPPORT", "PARTICIPANT_SUPPORT", "MTLS_CERTIFICATE_EXPIRY", "CONFIDENTIAL_DISCLOSURE_REQUEST", "NEXUS_PORTAL_SUPPORT", "REFERENCE_DATA_CHANGE", "PAYMENT_RECALL", "PAYMENT_INFORMATION_REQUEST", "IPSO_ONBOARDING_APPLICATION", "PSP_ONBOARDING_APPLICATION", "SAP_ONBOARDING_APPLICATION", "PDO_ONBOARDING_APPLICATION", "FXP_KYB_REQUEST", "DIRECT_PARTICIPANT_WITHDRAWAL", "TECHNICAL_INCIDENT", "SECURITY_INCIDENT", "PARTICIPANT_OUTAGE", "PLANNED_DOWNTIME", "DISPUTE_TRANSACTION_PROCESSING", "DISPUTE_FRAUD_OR_SCAM", "DISPUTE_SCHEME_NON_COMPLIANCE", "RECONCILIATION_DISCREPANCY", "SCHEME_FEE_QUERY", "FEEDBACK_AND_COMPLAINT"], "description": "Supported ticket type, not a ServiceNow table or record class. The enum is exactly the set of service catalog items for which an IPSO or direct participant is the requester, and each value carries the catalog item name, category and recipient shown in the ServiceRequests tag. Catalog items sourced by NGO, NGP, FXP or Nexus automation are not accepted enum values."}, "ServiceRequestPayloadVersion": {"type": "string", "enum": ["1.0"], "description": "Version of the payload contract for the selected requestCode, independent of API /v1 and delivery release. Validate the complete code/version/recipient combination; never silently default or reinterpret unsupported versions."}, "IPSOId": {"type": "string", "minLength": 15, "maxLength": 15, "pattern": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{3}\\.[A-Z]{3}$", "description": "Canonical immutable IPSOId value object: ISO 9362 11-character uppercase BIC, a dot and ISO 4217 currency code. Must resolve to the registered IPSO in the authenticated environment; syntax alone grants no communication entitlement. Not a country code, display name, email or ServiceNow sys_id.", "example": "MASSGSGSGSG.SGD"}, "FXPId": {"type": "string", "minLength": 1, "maxLength": 128, "description": "Scheme-assigned identifier of a registered FX Provider, as carried on Nexus participant reference data. Must resolve to an active FXP in the authenticated environment; syntax alone grants no communication entitlement. The canonical identifier format is a publication gate.", "example": "FXP-SG-0001"}, "NgoServiceRequestRecipient": {"type": "object", "additionalProperties": false, "required": ["type"], "properties": {"type": {"const": "NGO"}}, "description": "NGO support recipient. No client-selected organisation ID, assignment group or fulfilment system."}, "NgpServiceRequestRecipient": {"type": "object", "additionalProperties": false, "required": ["type"], "properties": {"type": {"const": "NGP"}}, "description": "NGP scheme-authority recipient, for matters NGP owns such as suspension or termination challenges, confidential-information disclosure, scheme-fee queries and tracked NGP correspondence. A single scheme authority, so no identifier is supplied."}, "IpsoServiceRequestRecipient": {"type": "object", "additionalProperties": false, "required": ["type", "ipsoId"], "properties": {"type": {"const": "IPSO"}, "ipsoId": {"$ref": "#/components/schemas/IPSOId"}}, "description": "Exactly one counterparty IPSO, eligible to receive this request type from the sender in the same authenticated environment. Active status, distinctness from the sender and type-specific entitlement are runtime authorisation checks. No self or bulk recipient."}, "FxpServiceRequestRecipient": {"type": "object", "additionalProperties": false, "required": ["type", "fxpId"], "properties": {"type": {"const": "FXP"}, "fxpId": {"$ref": "#/components/schemas/FXPId"}}, "description": "Exactly one registered FXP, eligible to receive due-diligence submissions from the sender in the same authenticated environment. Active status and entitlement are runtime authorisation checks."}, "ServiceRequestRecipient": {"oneOf": [{"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, {"$ref": "#/components/schemas/NgpServiceRequestRecipient"}, {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, {"$ref": "#/components/schemas/FxpServiceRequestRecipient"}], "description": "Intended business recipient, fixed per requestCode: NGO for support, incident, downtime, reference-data, onboarding and participant-lifecycle requests; NGP for scheme-authority matters; a counterparty IPSO for disputes, recalls, payment-information requests and tracked participant communication; an FXP for due-diligence submissions. NGO operates the intake in every case. This field does not select a network destination or broaden the caller's access."}, "SupportRequestPayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own support system. Not an idempotency key, ServiceNow ID or routing instruction."}}, "description": "Version 1.0 payload for TECHNICAL_SUPPORT and PARTICIPANT_SUPPORT. An empty object is valid because subject and description carry the request. Only clientReference is accepted as structured context. Specialised workflow fields, UETRs, attachments and arbitrary nested properties are not accepted and must not be smuggled into free text to invoke a workflow."}, "IncidentReportPayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own incident system."}, "detectedAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "Optional UTC instant at which the participant detected the incident."}}, "description": "Version 1.0 payload for TECHNICAL_INCIDENT and SECURITY_INCIDENT. Subject and description carry the incident narrative; no credentials, keys, raw payment messages or customer data. An unplanned outage of the submitting IPSO is its own catalog item, PARTICIPANT_OUTAGE, not a technical incident."}, "ParticipantOutagePayloadV1": {"type": "object", "additionalProperties": false, "required": ["outageStartedAt"], "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own incident system."}, "outageStartedAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC instant at which the submitting IPSO became unavailable."}, "expectedRecoveryAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "Optional UTC estimate of recovery; omit while recovery is not yet confirmed. Must not precede outageStartedAt."}}, "description": "Version 1.0 payload for PARTICIPANT_OUTAGE, reporting a current unplanned outage of the submitting IPSO. The Payment Processing API admi.004 notification is the primary channel for this item; this intake and the Service Desk UI are the alternative channels used when the payment flow is unavailable."}, "CommunicationPayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting participant's own correspondence system."}}, "description": "Version 1.0 payload for FEEDBACK_AND_COMPLAINT. Subject and description carry the feedback or complaint; NGO owns the documented investigation and resolution. No attachments or attachment links."}, "ReferenceDataChangePayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own change system."}, "requestedEffectiveDate": {"type": "string", "format": "date", "description": "Optional requested effective date for the change. A request, not an approval; NGO governs when a change takes effect."}}, "description": "Version 1.0 payload for REFERENCE_DATA_CHANGE. Describe the requested addition or amendment in the description; this API does not apply configuration changes and is not a Configuration Command API substitute."}, "CertificateSupportPayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own certificate or change system."}, "certificateExpiresAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "Optional UTC expiry instant of the affected certificate."}}, "description": "Version 1.0 payload for MTLS_CERTIFICATE_EXPIRY. Coordinates renewal only. Never include certificate material, private keys, passphrases or any credential, in the payload or in free text; a suspected compromise is a SECURITY_INCIDENT, not an expiry request."}, "PaymentReferencePayloadV1": {"type": "object", "additionalProperties": false, "required": ["uetr"], "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own case system."}, "uetr": {"$ref": "#/components/schemas/Uetr", "description": "The single payment the request concerns."}}, "description": "Version 1.0 payload for PAYMENT_RECALL and PAYMENT_INFORMATION_REQUEST. Exactly one payment per submission, for its full original amount; partial recalls are not supported. Raising either request does not recall, cancel, reverse or otherwise alter the payment. Where a recall is accepted, the destination side initiates a separate Return Payment referencing the original UETR; the original payment keeps its finality."}, "BillingQueryPayloadV1": {"type": "object", "additionalProperties": false, "required": ["billingPeriod"], "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own finance system."}, "billingPeriod": {"type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "description": "Billing month in YYYY-MM that the query concerns.", "example": "2026-09"}, "documentReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional report or statement reference the query concerns."}}, "description": "Version 1.0 payload for SCHEME_FEE_QUERY. Covers Scheme Fee calculation and supporting report data for NGP investigation."}, "OnboardingApplicationPayloadV1": {"type": "object", "additionalProperties": false, "required": ["applicantType"], "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting participant's own onboarding system."}, "applicantType": {"type": "string", "enum": ["IPSO", "PSP", "SAP", "PDO"], "description": "Category of participant the application concerns. Must be consistent with the selected requestCode."}, "applicantReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional institutional reference for the applicant. Never a natural-person identifier."}}, "description": "Version 1.0 payload for IPSO_ONBOARDING_APPLICATION, PSP_ONBOARDING_APPLICATION, SAP_ONBOARDING_APPLICATION, PDO_ONBOARDING_APPLICATION and FXP_KYB_REQUEST. Initiates the governed onboarding case only; due-diligence documents, questionnaires and evidence are exchanged through the authorised onboarding channel, never through this API."}, "WithdrawalRequestPayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting participant's own case system."}, "requestedEffectiveDate": {"type": "string", "format": "date", "description": "Optional requested withdrawal date. A request, not a decision; the governed offboarding process determines the actual effective date."}}, "description": "Version 1.0 payload for DIRECT_PARTICIPANT_WITHDRAWAL. The submitting participant is the withdrawing participant, derived from credentials and never named in the body. Submitting the request begins governed offboarding; it does not itself withdraw the participant."}, "PlannedDowntimePayloadV1": {"type": "object", "additionalProperties": false, "required": ["plannedStartAt"], "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own change or maintenance system."}, "plannedStartAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC instant at which planned downtime starts, or at which recovery is planned when notifying recovery only."}, "plannedEndAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "Optional UTC instant at which planned downtime ends; must not precede plannedStartAt."}}, "description": "Version 1.0 payload for PLANNED_DOWNTIME. Notifies NGO in advance of planned downtime or planned recovery of the submitting IPSO. The Payment Processing API admi.004 notification is the primary channel; this intake and the Service Desk UI are the alternative channels used when the payment flow is unavailable."}, "DisputePayloadV1": {"type": "object", "additionalProperties": false, "properties": {"clientReference": {"$ref": "#/components/schemas/Identifier", "description": "Optional PII-free reference in the submitting IPSO's own dispute or case system; not the deduplication key."}, "uetr": {"$ref": "#/components/schemas/Uetr", "description": "Optional UETR of the single disputed payment. Omit for a scheme non-compliance dispute that does not concern one payment."}}, "description": "Version 1.0 payload for the four Dispute & Resolution Management intake items: DISPUTE_TRANSACTION_PROCESSING, DISPUTE_FRAUD_OR_SCAM, DISPUTE_SCHEME_NON_COMPLIANCE and RECONCILIATION_DISCREPANCY. The dispute category is the requestCode itself, so no separate category field is carried in the payload. Each item retains its bilateral-resolution entry criteria; the responding IPSO owns the dispute response under the governed dispute workflow, and NGO provides intake and routing only."}, "ServiceRequestSubmission": { "type": "object", "additionalProperties": false, "required": ["category", "requestCode", "payloadVersion", "recipient", "subject", "description", "payload"], "description": "Stable request contract for submitting a Service Desk ticket. Exactly one supported ticket type must match: requestCode, category, payloadVersion and recipient type are a single approved service catalog combination, and any other combination is rejected rather than reinterpreted. The body contains no sender identity, environment override, backend record class, priority, assignment group, callback, attachment or ServiceNow identifier. Dynamic payloads remain closed and validated per profile.", "properties": { "category": {"$ref": "#/components/schemas/ServiceRequestCategory"}, "requestCode": {"$ref": "#/components/schemas/ServiceRequestCode"}, "payloadVersion": {"$ref": "#/components/schemas/ServiceRequestPayloadVersion"}, "recipient": {"$ref": "#/components/schemas/ServiceRequestRecipient"}, "subject": {"type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S", "description": "Non-blank, PII-free plain-text subject; no secrets, executable markup or file content."}, "description": {"type": "string", "minLength": 1, "maxLength": 10000, "pattern": "\\S", "description": "Non-blank, PII-free plain-text explanation. Do not include customer data, credentials, private keys, raw payment messages, attachments or attachment links. Free text never changes the selected profile or its permissions."}, "payload": {"type": "object", "description": "Structured business context validated against requestCode + payloadVersion. The selected profile determines accepted fields and values; no arbitrary ServiceNow field passthrough."} }, "oneOf": [ {"title": "Technical support or enquiry to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "TECHNICAL_SUPPORT"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/SupportRequestPayloadV1"}}}, {"title": "General support request or enquiry to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "PARTICIPANT_SUPPORT"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/SupportRequestPayloadV1"}}}, {"title": "mTLS certificate expiry support request to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "MTLS_CERTIFICATE_EXPIRY"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/CertificateSupportPayloadV1"}}}, {"title": "Confidential information disclosure request to NGP, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "CONFIDENTIAL_DISCLOSURE_REQUEST"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgpServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/SupportRequestPayloadV1"}}}, {"title": "Nexus Portal or PAT integration support to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "NEXUS_PORTAL_SUPPORT"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/SupportRequestPayloadV1"}}}, {"title": "Participant reference-data change request to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "REFERENCE_DATA_CHANGE"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/ReferenceDataChangePayloadV1"}}}, {"title": "Payment recall request to the counterparty IPSO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "PAYMENT_RECALL"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/PaymentReferencePayloadV1"}}}, {"title": "Further payment information request to the counterparty IPSO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_SUPPORT_AND_REQUESTS"}, "requestCode": {"const": "PAYMENT_INFORMATION_REQUEST"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/PaymentReferencePayloadV1"}}}, {"title": "IPSO onboarding application to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_MANAGEMENT"}, "requestCode": {"const": "IPSO_ONBOARDING_APPLICATION"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"allOf": [{"$ref": "#/components/schemas/OnboardingApplicationPayloadV1"}, {"properties": {"applicantType": {"const": "IPSO"}}}]}}}, {"title": "PSP onboarding application to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_MANAGEMENT"}, "requestCode": {"const": "PSP_ONBOARDING_APPLICATION"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"allOf": [{"$ref": "#/components/schemas/OnboardingApplicationPayloadV1"}, {"properties": {"applicantType": {"const": "PSP"}}}]}}}, {"title": "SAP onboarding application to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_MANAGEMENT"}, "requestCode": {"const": "SAP_ONBOARDING_APPLICATION"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"allOf": [{"$ref": "#/components/schemas/OnboardingApplicationPayloadV1"}, {"properties": {"applicantType": {"const": "SAP"}}}]}}}, {"title": "PDO onboarding application to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_MANAGEMENT"}, "requestCode": {"const": "PDO_ONBOARDING_APPLICATION"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"allOf": [{"$ref": "#/components/schemas/OnboardingApplicationPayloadV1"}, {"properties": {"applicantType": {"const": "PDO"}}}]}}}, {"title": "CBDDQ or FXP KYB submission to the selected FXP, version 1.0", "properties": {"category": {"const": "PARTICIPANT_MANAGEMENT"}, "requestCode": {"const": "FXP_KYB_REQUEST"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/FxpServiceRequestRecipient"}, "payload": {"allOf": [{"$ref": "#/components/schemas/OnboardingApplicationPayloadV1"}, {"properties": {"applicantType": {"const": "PSP"}}}]}}}, {"title": "Direct participant withdrawal request to NGO, version 1.0", "properties": {"category": {"const": "PARTICIPANT_MANAGEMENT"}, "requestCode": {"const": "DIRECT_PARTICIPANT_WITHDRAWAL"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/WithdrawalRequestPayloadV1"}}}, {"title": "Technical incident report to NGO, version 1.0", "properties": {"category": {"const": "INCIDENT_AND_AVAILABILITY_MANAGEMENT"}, "requestCode": {"const": "TECHNICAL_INCIDENT"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/IncidentReportPayloadV1"}}}, {"title": "Security incident report to NGO, version 1.0", "properties": {"category": {"const": "INCIDENT_AND_AVAILABILITY_MANAGEMENT"}, "requestCode": {"const": "SECURITY_INCIDENT"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/IncidentReportPayloadV1"}}}, {"title": "Unplanned participant outage report to NGO, version 1.0", "properties": {"category": {"const": "INCIDENT_AND_AVAILABILITY_MANAGEMENT"}, "requestCode": {"const": "PARTICIPANT_OUTAGE"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/ParticipantOutagePayloadV1"}}}, {"title": "Planned downtime or recovery notification to NGO, version 1.0", "properties": {"category": {"const": "INCIDENT_AND_AVAILABILITY_MANAGEMENT"}, "requestCode": {"const": "PLANNED_DOWNTIME"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/PlannedDowntimePayloadV1"}}}, {"title": "Formal transaction-processing dispute with the responding IPSO, version 1.0", "properties": {"category": {"const": "DISPUTE_AND_RESOLUTION_MANAGEMENT"}, "requestCode": {"const": "DISPUTE_TRANSACTION_PROCESSING"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/DisputePayloadV1"}}}, {"title": "Formal fraud or scam dispute with the responding IPSO, version 1.0", "properties": {"category": {"const": "DISPUTE_AND_RESOLUTION_MANAGEMENT"}, "requestCode": {"const": "DISPUTE_FRAUD_OR_SCAM"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/DisputePayloadV1"}}}, {"title": "Formal scheme non-compliance dispute with the responding IPSO, version 1.0", "properties": {"category": {"const": "DISPUTE_AND_RESOLUTION_MANAGEMENT"}, "requestCode": {"const": "DISPUTE_SCHEME_NON_COMPLIANCE"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/DisputePayloadV1"}}}, {"title": "Reconciliation discrepancy report to the counterparty IPSO, version 1.0", "properties": {"category": {"const": "DISPUTE_AND_RESOLUTION_MANAGEMENT"}, "requestCode": {"const": "RECONCILIATION_DISCREPANCY"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/IpsoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/DisputePayloadV1"}}}, {"title": "Scheme Fee calculation or report query to NGP, version 1.0", "properties": {"category": {"const": "DISPUTE_AND_RESOLUTION_MANAGEMENT"}, "requestCode": {"const": "SCHEME_FEE_QUERY"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgpServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/BillingQueryPayloadV1"}}}, {"title": "Feedback or complaint to NGO, version 1.0", "properties": {"category": {"const": "FEEDBACK_AND_COMPLAINT"}, "requestCode": {"const": "FEEDBACK_AND_COMPLAINT"}, "payloadVersion": {"const": "1.0"}, "recipient": {"$ref": "#/components/schemas/NgoServiceRequestRecipient"}, "payload": {"$ref": "#/components/schemas/CommunicationPayloadV1"}}} ] }, "ServiceRequestId": {"type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "description": "Opaque NGO-generated intake identifier, stable across retries and independent of any ServiceNow record ID or ticket number. Mapped internally to nexus_correlation_id for downstream deduplication and to the ticket reference in the authorised Service Desk."}, "ServiceRequestReceipt": {"type": "object", "additionalProperties": false, "required": ["requestId", "status", "acceptedAt"], "properties": {"requestId": {"$ref": "#/components/schemas/ServiceRequestId"}, "status": {"const": "ACCEPTED", "description": "Immutable intake acknowledgement, not the current ticket lifecycle, delivery state or outcome."}, "acceptedAt": {"type": "string", "format": "date-time", "pattern": "Z$", "description": "Server-recorded UTC acceptance instant, unchanged on replay."}}, "description": "Durable acceptance by NGO. Does not promise that a downstream ticket already exists. No ServiceNow-specific identifiers, polling URL or mutable processing status are exposed by this create-only API."}, "OperationalQuery": { "type": "object", "description": "Schema for the decoded query-parameter map, not a request body. Enforce first-request versus cursor-only alternatives server-side; standard OpenAPI parameter required flags cannot express them. First requests require dates and may filter directly by status; there is no view parameter. Also validate inclusive date difference <=31, retention and no future/reversed dates. pendingAgeBucket intersects current PDNG with the date range and any explicit status; incompatible status/bucket selections produce an empty eligible population. Reject unknown or repeated keys before decoding.", "examples": [{"fromDate": "20260916", "toDate": "20260916", "status": "PDNG", "pageSize": 2}, {"cursor": "c-example-ipso-page-2"}], "oneOf": [ {"title": "New logical query", "additionalProperties": false, "required": ["fromDate", "toDate"], "properties": {"fromDate": {"$ref": "#/components/parameters/FromDate/schema"}, "toDate": {"$ref": "#/components/parameters/ToDate/schema"}, "sendingIpso": {"$ref": "#/components/parameters/SendingIpso/schema"}, "receivingIpso": {"$ref": "#/components/parameters/ReceivingIpso/schema"}, "direction": {"$ref": "#/components/parameters/Direction/schema"}, "pspId": {"$ref": "#/components/parameters/PspId/schema"}, "status": {"$ref": "#/components/parameters/Status/schema"}, "statusSource": {"$ref": "#/components/parameters/StatusSource/schema"}, "pendingAgeBucket": {"$ref": "#/components/parameters/PendingAgeBucket/schema"}, "pageSize": {"$ref": "#/components/parameters/PageSize/schema"}}}, {"title": "Continuation of an admitted query", "additionalProperties": false, "required": ["cursor"], "properties": {"cursor": {"$ref": "#/components/parameters/Cursor/schema"}}} ] }, "Uetr": {"type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}, "Identifier": {"type": "string", "minLength": 1, "maxLength": 128, "description": "Source-owned institutional/operational identifier, not customer PII."}, "Currency": {"type": "string", "pattern": "^[A-Z]{3}$", "description": "Valid ISO 4217 code."}, "NexusMessageIdentifier": {"type": "string", "minLength": 35, "maxLength": 35, "pattern": "^[0-9]{8}NXPS081[A-Z0-9]{8}[A-Z0-9]{11}X$", "description": "Nexus message identifier of the original pacs.008, 35 characters: YYYYMMDD + NXPS081 + sequence(8) + sender BIC-11 + literal X."}, "Max35Reference": {"type": "string", "minLength": 1, "maxLength": 35, "description": "Source-owned reference, at most 35 characters, as carried in the camt.054 file. Nexus character restrictions apply."}, "Amount": {"type": "string", "pattern": "^(0|[1-9][0-9]{0,12})(\\.[0-9]{1,5})?$", "description": "Exact non-negative decimal; preserve source precision and pair with currency. At most 18 total digits and 5 fractional digits, matching the XML amount limits."}, "PaymentStatus": {"type": "string", "enum": ["ACCC", "RJCT", "PDNG", "BLCK"], "description": "Nexus-observed source state, not a domestic balance or booking. The same values as camt.054 Ntry/Sts/Prtry; the file does not use Ntry/Sts/Cd. ACWP is received by Nexus but never sent, so it does not appear in this feed or in report totals."}, "StatusSource": {"type": "string", "enum": ["NEXUS", "DESTINATION"]}, "DataQuality": {"type": "string", "enum": ["complete", "partial", "stale"]}, "Reason": {"type": "object", "additionalProperties": false, "required": ["code", "description"], "properties": {"code": {"type": "string", "minLength": 1}, "description": {"type": "string", "minLength": 1, "description": "Approved PII-free reason text, not raw participant/customer free text."}}}, "PendingReasonCode": { "type": "string", "enum": ["AWAITING_DESTINATION_RESPONSE", "DESTINATION_DELIVERY_UNCONFIRMED", "DESTINATION_UNREACHABLE", "UNDER_INVESTIGATION", "INVALID_STATUS_RECEIVED", "DESTINATION_PROCESSING"], "description": "Closed set of reasons a payment is currently PDNG. No value implies finality, a rejection or a completed payment, and none of them is a payment status in its own right. The first five are Nexus-observed (statusSource NEXUS); DESTINATION_PROCESSING is reported by the destination IPSO (statusSource DESTINATION). The set is closed: a response never carries a value outside it.\n\n| Code | Meaning |\n| --- | --- |\n| AWAITING_DESTINATION_RESPONSE | Dispatched to the destination IPSO; no status returned and the settlement timer has not expired. |\n| DESTINATION_DELIVERY_UNCONFIRMED | Delivery to the destination IPSO could not be confirmed after the retry policy was exhausted. Delivery is uncertain, not refused. |\n| DESTINATION_UNREACHABLE | Persistent connectivity, authentication or routing failure to the destination IPSO. |\n| UNDER_INVESTIGATION | The settlement timer expired and the enquiry cadence is running. This remains the reason for as long as enquiry continues, including after the investigation window closes; internal escalation and ticketing do not change it. |\n| INVALID_STATUS_RECEIVED | A destination status message arrived but failed validation, so no status was applied. A valid status message is still awaited. |\n| DESTINATION_PROCESSING | The destination IPSO reported the payment as still in progress. |" }, "PendingReason": { "type": "object", "additionalProperties": false, "required": ["code", "description"], "description": "Why the payment is currently PDNG. Present only when the reason is known; absence is a missing fact, never an inferred outcome. Reporting classifies the reason from source facts and does not change payment state.", "properties": { "code": {"$ref": "#/components/schemas/PendingReasonCode"}, "description": {"type": "string", "minLength": 1, "description": "Approved PII-free reason text, not raw participant/customer free text."}, "destinationReasonCode": {"type": "string", "minLength": 1, "description": "ISO 20022 StsRsnInf/Rsn/Cd exactly as supplied by the destination IPSO on its interim pacs.002. Omitted whenever the destination supplied no reason, and only ever present with code DESTINATION_PROCESSING. Never populated by Nexus from its own classification."} }, "x-producer-validation": {"destinationReasonCode": "Emit only alongside code DESTINATION_PROCESSING, and only with a reason the destination IPSO actually supplied. Enforce this pairing server-side; expressing it as a JSON Schema conditional alongside additionalProperties is not reliably interpreted by current OpenAPI tooling."} }, "BIC": {"type": "string", "pattern": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$", "description": "ISO 9362 Business Identifier Code as carried in camt.054 FinInstnId/BICFI: a four-letter institution code, a two-letter ISO 3166-1 country code, a two-character location code and an optional three-character branch code, giving 8 or 11 characters. Institutional identifier only, never customer data.", "example": "BANKSGSGAXX"}, "LEI": {"type": "string", "pattern": "^[A-Z0-9]{18}[0-9]{2}$", "description": "ISO 17442 Legal Entity Identifier as carried in camt.054 FinInstnId/LEI. Institutional identifier only, never customer data.", "example": "9845001EXAMPLE000017"}, "AgentIdentification": { "type": "object", "additionalProperties": false, "required": ["scheme", "id"], "description": "An agent institution as identified in camt.054 FinInstnId, copied from the pacs.008: exactly one of BICFI, LEI or ClrSysMmbId. scheme names the form and id carries the value; clearingSystemCode accompanies a clearing-system member ID when the source supplied it. Institutional identifier only, never customer data.", "oneOf": [{"title": "BIC", "properties": {"scheme": {"const": "BIC"}, "id": {"$ref": "#/components/schemas/BIC"}}, "not": {"required": ["clearingSystemCode"]}}, {"title": "LEI", "properties": {"scheme": {"const": "LEI"}, "id": {"$ref": "#/components/schemas/LEI"}}, "not": {"required": ["clearingSystemCode"]}}, {"title": "Clearing-system member ID", "properties": {"scheme": {"const": "CLEARING_MEMBER_ID"}}}], "properties": { "scheme": {"type": "string", "enum": ["BIC", "LEI", "CLEARING_MEMBER_ID"], "description": "BIC is FinInstnId/BICFI, LEI is FinInstnId/LEI and CLEARING_MEMBER_ID is FinInstnId/ClrSysMmbId/MmbId."}, "id": {"type": "string", "minLength": 1, "maxLength": 35, "description": "The identifier value, in the form named by scheme."}, "clearingSystemCode": {"type": "string", "minLength": 1, "maxLength": 5, "description": "FinInstnId/ClrSysMmbId/ClrSysId/Cd, an ISO external clearing system code. Only with CLEARING_MEMBER_ID; omitted when the source did not supply it."} } }, "AccountIdentification": { "type": "object", "additionalProperties": false, "required": ["scheme", "id"], "description": "An account identifier copied from the pacs.008, as carried in camt.054 RltdPties/DbtrAcct/Id or RltdPties/CdtrAcct/Id. Identifier only: no account name, proxy, type or currency. Use it for reconciliation; it is not a query filter and must not be logged.", "oneOf": [{"title": "IBAN", "properties": {"scheme": {"const": "IBAN"}, "id": {"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$"}}}, {"title": "Other account identifier", "properties": {"scheme": {"const": "OTHER"}}}], "properties": { "scheme": {"type": "string", "enum": ["IBAN", "OTHER"], "description": "IBAN is Id/IBAN; OTHER is Id/Othr/Id, such as a domestic account number."}, "id": {"type": "string", "minLength": 1, "maxLength": 34, "description": "The account identifier, in the form named by scheme."} } }, "EntryAmount": {"type": "object", "additionalProperties": false, "required": ["amount", "currency"], "properties": {"amount": {"$ref": "#/components/schemas/Amount"}, "currency": {"$ref": "#/components/schemas/Currency"}}, "description": "An amount with its currency, mirroring the camt.054 Amt element and its Ccy attribute. The currency always travels with the amount; never sum amounts across currencies."}, "CreditDebitIndicator": {"type": "string", "enum": ["CRDT", "DBIT"], "description": "camt.054 CdtDbtInd. Direction of the entry relative to the reported Nexus clearing account. Equivalent to the direction field expressed in ISO vocabulary: an outbound payment is DBIT and an inbound payment is CRDT."}, "BankTransactionCode": { "type": "object", "additionalProperties": false, "required": ["domain", "family", "subFamily"], "description": "camt.054 BkTxCd. Domain is always PMNT and subFamily always XBCT (cross-border credit transfer). Family encodes the Nexus role for this entry and is a third equivalent view of the same fact as direction and creditDebitIndicator.", "properties": { "domain": {"type": "string", "const": "PMNT", "description": "BkTxCd/Domn/Cd."}, "family": {"type": "string", "enum": ["IRCT", "RRCT"], "description": "BkTxCd/Domn/Fmly/Cd. IRCT when Nexus acts as Source IPSO for this entry, RRCT as Destination IPSO."}, "subFamily": {"type": "string", "const": "XBCT", "description": "BkTxCd/Domn/Fmly/SubFmlyCd."} } }, "TransactionReferences": { "type": "object", "additionalProperties": false, "required": ["uetr", "messageId", "endToEndId"], "description": "camt.054 NtryDtls/TxDtls/Refs. Every value is copied unchanged from the original pacs.008 except clearingSystemReference, which Nexus assigns. UETR is the primary match key; the others are available for cross-validation. A reference the source did not supply is omitted rather than defaulted. messageId, endToEndId and uetr are required, as in the camt.054 file. MsgId follows the 35-character Nexus message-identifier format and the other references are at most 35 characters with Nexus character restrictions.", "properties": { "messageId": {"$ref": "#/components/schemas/NexusMessageIdentifier", "description": "Refs/MsgId."}, "instructionId": {"$ref": "#/components/schemas/Max35Reference", "description": "Refs/InstrId."}, "endToEndId": {"$ref": "#/components/schemas/Max35Reference", "description": "Refs/EndToEndId."}, "uetr": {"$ref": "#/components/schemas/Uetr", "description": "Refs/UETR. Identical to the record's own uetr; repeated here so the Refs group maps one-to-one onto the file."}, "transactionId": {"$ref": "#/components/schemas/Max35Reference", "description": "Refs/TxId."}, "clearingSystemReference": {"$ref": "#/components/schemas/Max35Reference", "description": "Refs/ClrSysRef, assigned by Nexus."} } }, "CurrencyExchange": { "type": "object", "additionalProperties": false, "required": ["sourceCurrency", "exchangeRate"], "description": "camt.054 AmtDtls/InstdAmt/CcyXchg. Carries the agreed exchange rate applied to this payment. Transaction-time facts only; never re-derived from a current rate. SrcCcy and XchgRate are required and TrgtCcy is optional, as in the file. The same structure is used under both InstdAmt and TxAmt.", "properties": { "sourceCurrency": {"$ref": "#/components/schemas/Currency", "description": "CcyXchg/SrcCcy. Equal to the currency component of the sendingIpso key."}, "targetCurrency": {"$ref": "#/components/schemas/Currency", "description": "CcyXchg/TrgtCcy. Optional. Equal to the currency component of the receivingIpso key."}, "exchangeRate": {"type": "string", "pattern": "^(0|[1-9][0-9]{0,2})\\.[0-9]{8}$", "description": "CcyXchg/XchgRate as an exact decimal string with exactly 8 fractional digits and at most 11 total digits (XSD totalDigits 11), as in the file. Required whenever currencyExchange is present.", "example": "3.54200000"} } }, "AmountDetails": { "type": "object", "additionalProperties": false, "required": ["instructedAmount", "transactionAmount"], "description": "camt.054 AmtDtls. The instructed amount with its embedded currency exchange. The instructed amount (AmtDtls/InstdAmt) and the transaction amount (AmtDtls/TxAmt) are distinct and must not be substituted for one another.", "properties": { "instructedAmount": {"$ref": "#/components/schemas/EntryAmount", "description": "AmtDtls/InstdAmt/Amt and its Ccy."}, "currencyExchange": {"$ref": "#/components/schemas/CurrencyExchange", "description": "AmtDtls/InstdAmt/CcyXchg. Omitted where no exchange applies."}, "transactionAmount": {"$ref": "#/components/schemas/TransactionAmount"} } }, "TransactionAmount": { "type": "object", "additionalProperties": false, "required": ["amount", "currency", "currencyExchange"], "description": "camt.054 AmtDtls/TxAmt: the transaction amount with its currency exchange. Distinct from the instructed amount.", "properties": { "amount": {"$ref": "#/components/schemas/Amount", "description": "AmtDtls/TxAmt/Amt."}, "currency": {"$ref": "#/components/schemas/Currency", "description": "The Ccy attribute of AmtDtls/TxAmt/Amt."}, "currencyExchange": {"$ref": "#/components/schemas/CurrencyExchange", "description": "AmtDtls/TxAmt/CcyXchg."} } }, "ChargeRecord": { "type": "object", "additionalProperties": false, "required": ["amount", "currency", "creditDebitIndicator", "type", "bearer", "agent"], "description": "One camt.054 Chrgs/Rcrd. Nexus publishes one record for the Source PSP fee and one for the Destination PSP fee, each in its own currency. Charge records are never netted or summed across currencies. The file carries exactly two Chrgs/Rcrd entries, each with its agent, and so does this feed. creditDebitIndicator, type and bearer are Nexus-derived enrichment: the file carries none of Rcrd/CdtDbtInd, Rcrd/Tp or Rcrd/Br.", "properties": { "amount": {"$ref": "#/components/schemas/Amount", "description": "Rcrd/Amt."}, "currency": {"$ref": "#/components/schemas/Currency", "description": "The Ccy attribute of Rcrd/Amt."}, "creditDebitIndicator": {"$ref": "#/components/schemas/CreditDebitIndicator", "description": "Nexus-derived enrichment. The camt.054 file does not carry CdtDbtInd on Chrgs/Rcrd."}, "type": {"type": "string", "enum": ["SPSP", "DPSP"], "description": "Nexus-derived enrichment; the camt.054 file does not carry Rcrd/Tp. SPSP is the Source PSP fee and DPSP the Destination PSP fee."}, "bearer": {"type": "string", "const": "DEBT", "description": "Nexus-derived enrichment; the camt.054 file does not carry Rcrd/Br. Always DEBT under the Nexus scheme rules."}, "agent": {"$ref": "#/components/schemas/AgentIdentification", "description": "Rcrd/Agt/FinInstnId, the institution the charge applies to."} } }, "TransactionState": { "type": "object", "required": ["uetr", "status", "statusSource", "acceptedAt", "updatedAt"], "allOf": [{"if": {"required": ["status"], "properties": {"status": {"const": "PDNG"}}}, "then": {"not": {"required": ["finalStatusAt"]}}, "else": {"required": ["finalStatusAt"], "not": {"required": ["pendingReason"]}}}, {"if": {"required": ["status"], "properties": {"status": {"const": "RJCT"}}}, "then": {"required": ["rejectionReason"]}, "else": {"not": {"required": ["rejectionReason"]}}}], "description": "Optional facts are omitted if unavailable, never fabricated. Status rules: finalStatusAt is present for ACCC, RJCT and BLCK and absent for PDNG; rejectionReason is present only for RJCT; pendingReason only for PDNG. No raw messages, customer PII or full event history.", "properties": { "uetr": {"$ref": "#/components/schemas/Uetr"}, "status": {"$ref": "#/components/schemas/PaymentStatus"}, "statusSource": {"$ref": "#/components/schemas/StatusSource"}, "acceptedAt": {"type": "string", "format": "date-time", "description": "The instant Nexus recorded the transaction as accepted. It assigns the Nexus Day and is the basis of the date filters; pending age is measured from it. No camt.054 counterpart."}, "updatedAt": {"type": "string", "format": "date-time", "description": "Timestamp of the latest source payment-state update."}, "finalStatusAt": {"type": "string", "format": "date-time", "description": "Present for ACCC, RJCT and BLCK; absent for PDNG."}, "rejectionReason": {"$ref": "#/components/schemas/Reason", "description": "Present only for RJCT, where it is required. camt.054 carries the status code but no status reason, so this fact has no counterpart in the file."}, "pendingReason": {"$ref": "#/components/schemas/PendingReason", "description": "Only for current PDNG. Omitted for any other status and whenever the reason is unknown. camt.054 carries the status code but no status reason, so this fact has no counterpart in the file."} } }, "Transaction": { "type": "object", "unevaluatedProperties": false, "allOf": [{"$ref": "#/components/schemas/TransactionState"}, {"if": {"required": ["status"], "properties": {"status": {"enum": ["ACCC", "BLCK"]}}}, "then": {"required": ["bookingDateTime"]}, "else": {"not": {"required": ["bookingDateTime"]}}}, {"if": {"required": ["status"], "properties": {"status": {"const": "PDNG"}}}, "then": {"required": ["pendingAgeSeconds"]}, "else": {"not": {"required": ["pendingAgeSeconds"]}}}, {"anyOf": [{"properties": {"direction": {"const": "outbound"}, "creditDebitIndicator": {"const": "DBIT"}, "bankTransactionCode": {"properties": {"family": {"const": "IRCT"}}}}}, {"properties": {"direction": {"const": "inbound"}, "creditDebitIndicator": {"const": "CRDT"}, "bankTransactionCode": {"properties": {"family": {"const": "RRCT"}}}}}]}], "required": ["entryAmount", "creditDebitIndicator", "bankTransactionCode", "references", "amountDetails", "charges", "debtorAccount", "creditorAccount", "instructingAgent", "instructedAgent", "debtorAgent", "creditorAgent", "intermediaryAgent1", "intermediaryAgent2", "direction", "sourceCountry", "destinationCountry"], "description": "One Operational Data Feed record: a reduced, normalised JSON representation of the corresponding camt.054 Ntry, plus the operational facts the file does not carry. It is not a lossless copy of every field the file carries.\n\nThe following feed fields correspond to camt.054 elements: entryAmount and creditDebitIndicator to Ntry/Amt and Ntry/CdtDbtInd, status to Ntry/Sts/Prtry (the file carries the status in the proprietary branch; Cd is not used), bookingDateTime to Ntry/BookgDt/DtTm, bankTransactionCode to Ntry/BkTxCd, references to NtryDtls/TxDtls/Refs, amountDetails to AmtDtls (InstdAmt and TxAmt), charges to Chrgs/Rcrd, debtorAccount and creditorAccount to RltdPties/DbtrAcct/Id and RltdPties/CdtrAcct/Id, instructingAgent, instructedAgent, debtorAgent, creditorAgent, intermediaryAgent1 and intermediaryAgent2 to RltdAgts, and acceptanceDateTime and interbankSettlementDate to RltdDts. The representation is JSON rather than XML, so the same facts can be matched across both channels without the file's element nesting or attributes. Agents carry every identification form the file allows: BIC, LEI or clearing-system member ID. charges carries Nexus-derived enrichment fields that have no XML counterpart under Chrgs/Rcrd (see ChargeRecord).\n\nThe operational facts have no camt.054 counterpart and are available only here: statusSource, acceptedAt, updatedAt, finalStatusAt, rejectionReason, pendingReason, pendingAgeSeconds, destinationAmount, sourceCountry, destinationCountry and direction. direction, creditDebitIndicator and bankTransactionCode.family are three equivalent views of the same role and never disagree.\n\nStatus rules: bookingDateTime is present only for ACCC and BLCK, and pendingAgeSeconds only for PDNG.", "properties": { "entryAmount": {"$ref": "#/components/schemas/EntryAmount", "description": "Ntry/Amt with its Ccy: the entry amount in the currency of the reported Nexus clearing account."}, "creditDebitIndicator": {"$ref": "#/components/schemas/CreditDebitIndicator"}, "bookingDateTime": {"type": "string", "format": "date-time", "description": "Ntry/BookgDt/DtTm: the timestamp of completion in the Nexus Gateway. Present only for ACCC and BLCK. It is not evidence of a domestic account booking."}, "bankTransactionCode": {"$ref": "#/components/schemas/BankTransactionCode"}, "references": {"$ref": "#/components/schemas/TransactionReferences"}, "amountDetails": {"$ref": "#/components/schemas/AmountDetails"}, "charges": {"type": "array", "minItems": 2, "maxItems": 2, "items": {"$ref": "#/components/schemas/ChargeRecord"}, "allOf": [{"contains": {"properties": {"type": {"const": "SPSP"}}}, "minContains": 1, "maxContains": 1}, {"contains": {"properties": {"type": {"const": "DPSP"}}}, "minContains": 1, "maxContains": 1}], "description": "Chrgs/Rcrd: exactly two records, one for the Source PSP fee (SPSP) and one for the Destination PSP fee (DPSP)."}, "debtorAccount": {"$ref": "#/components/schemas/AccountIdentification", "description": "RltdPties/DbtrAcct/Id: the debtor's account identifier, copied from the pacs.008."}, "creditorAccount": {"$ref": "#/components/schemas/AccountIdentification", "description": "RltdPties/CdtrAcct/Id: the creditor's account identifier, copied from the pacs.008."}, "instructingAgent": {"$ref": "#/components/schemas/AgentIdentification", "description": "RltdAgts/InstgAgt, copied from the pacs.008."}, "instructedAgent": {"$ref": "#/components/schemas/AgentIdentification", "description": "RltdAgts/InstdAgt, copied from the pacs.008."}, "debtorAgent": {"$ref": "#/components/schemas/AgentIdentification", "description": "RltdAgts/DbtrAgt, the Source PSP. Matched by pspId on an outbound payment."}, "creditorAgent": {"$ref": "#/components/schemas/AgentIdentification", "description": "RltdAgts/CdtrAgt, the Destination PSP. Matched by pspId on an inbound payment."}, "intermediaryAgent1": {"$ref": "#/components/schemas/AgentIdentification", "description": "RltdAgts/IntrmyAgt1, the Source SAP."}, "intermediaryAgent2": {"$ref": "#/components/schemas/AgentIdentification", "description": "RltdAgts/IntrmyAgt2, the Destination SAP."}, "acceptanceDateTime": {"type": "string", "format": "date-time", "description": "RltdDts/AccptncDtTm: the acceptance timestamp set by the Source PSP, copied from the pacs.008. Not the Nexus acceptance; see acceptedAt."}, "interbankSettlementDate": {"type": "string", "format": "date", "description": "RltdDts/IntrBkSttlmDt."}, "direction": {"type": "string", "enum": ["inbound", "outbound"], "description": "Operational view of the same role as creditDebitIndicator and bankTransactionCode.family, relative to the authenticated IPSO. No camt.054 counterpart."}, "sourceCountry": {"type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 source country. No camt.054 counterpart."}, "destinationCountry": {"type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 destination country. No camt.054 counterpart."}, "destinationAmount": {"$ref": "#/components/schemas/EntryAmount", "description": "Destination-leg amount and currency as presented on the Transaction Dashboard. No camt.054 counterpart: the file conveys the destination leg through instructedAmount and the applied exchange rate."}, "pendingAgeSeconds": {"type": "number", "minimum": 0, "description": "Present only for current PDNG, calculated at the page evaluatedAt from acceptedAt. A read-only reporting calculation with no camt.054 counterpart."} } }, "TransactionPage": { "description": "One page of at most 2,500 records from a logical query spanning at most 31 inclusive Nexus Days. Use nextCursor for remaining records; the page cap is not a total-result cap.", "type": "object", "additionalProperties": false, "required": ["authoritative", "items", "returnedCount", "dataAsOf", "evaluatedAt", "dataQuality"], "dependentRequired": {"nextCursor": ["cursorExpiresAt"], "cursorExpiresAt": ["nextCursor"]}, "properties": {"authoritative": {"const": false}, "items": {"type": "array", "maxItems": 2500, "items": {"$ref": "#/components/schemas/Transaction"}}, "returnedCount": {"type": "integer", "minimum": 0, "maximum": 2500, "description": "Equals items length; not total matching population."}, "dataAsOf": {"type": "string", "format": "date-time"}, "evaluatedAt": {"type": "string", "format": "date-time"}, "dataQuality": {"$ref": "#/components/schemas/DataQuality"}, "nextCursor": {"type": "string", "minLength": 1}, "cursorExpiresAt": {"type": "string", "format": "date-time"}} }, "TrackAndTraceResult": {"description": "Latest known state for one transaction within the retained history window, typically available within seconds. This lookup reads live payment records; it does not change payment records and is not for polling or bulk retrieval.", "allOf": [{"$ref": "#/components/schemas/TransactionState"}], "type": "object", "unevaluatedProperties": false, "required": ["authoritative", "dataAsOf", "dataQuality"], "properties": {"authoritative": {"const": false}, "dataAsOf": {"type": "string", "format": "date-time"}, "dataQuality": {"$ref": "#/components/schemas/DataQuality"}}}, "ReportDate": {"type": "string", "pattern": "^[0-9]{8}$", "description": "A real YYYYMMDD Nexus date; validate calendar and retrieval-window rules."}, "ReportChecksum": { "type": "object", "additionalProperties": false, "required": ["algorithm", "value"], "description": "One named checksum of the exact protected .xml.gpg bytes delivered by both API and SFTP, not the decrypted XML or manifest JSON. SHA256 is the only approved algorithm and is a cryptographic digest; it does not replace Nexus signature verification. New algorithms require an approved, published definition before the producer emits them.", "properties": { "algorithm": {"type": "string", "minLength": 1, "pattern": "^[A-Z][A-Z0-9-]*$", "not": {"pattern": "\\s"}, "examples": ["SHA256"], "description": "Canonical case-sensitive algorithm name with no whitespace. Deliberately an extensible response string, not a closed enum, so existing clients can tolerate additional algorithms. SHA256 is the only approved name and is mandatory."}, "value": {"type": "string", "minLength": 1, "pattern": "^[0-9a-f]+$", "not": {"pattern": "\\s"}, "description": "Lowercase hexadecimal digest with no whitespace, including leading zeroes. Exactly 64 characters for SHA256; any newly approved algorithm must publish its digest length and computation rules."} }, "allOf": [ {"if": {"required": ["algorithm"], "properties": {"algorithm": {"const": "SHA256"}}}, "then": {"properties": {"algorithm": {"const": "SHA256"}, "value": {"minLength": 64, "maxLength": 64}}}} ] }, "ReportChecksums": { "type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/components/schemas/ReportChecksum"}, "description": "Unordered algorithm/value entries. Exactly one SHA256 entry is required and must be neither missing, duplicated nor replaced by an unknown algorithm. Additional approved algorithms may be appended without changing the file shape. Clients locate the digest by algorithm, never by array position, tolerate unsupported additional entries and still verify SHA256 and the Nexus signature. Every algorithm name must be unique: contains/maxContains enforce the single mandatory name; the producer must also check uniqueness of any future names because uniqueItems alone compares whole objects, not algorithm keys.", "x-producer-validation": {"approvedAlgorithms": ["SHA256"], "uniqueBy": "algorithm", "extensionPolicy": "Approve and publish a new algorithm definition, update this producer allowlist and add its value constraints before emission. Keep the response algorithm field open and retain the mandatory SHA256 entry for manifestVersion 1.0."}, "allOf": [ {"contains": {"type": "object", "required": ["algorithm"], "properties": {"algorithm": {"const": "SHA256"}}}, "minContains": 1, "maxContains": 1} ] }, "ReportFile": { "type": "object", "additionalProperties": false, "required": ["sequence", "name", "records", "sizeBytes", "checksums", "url", "expiresAt"], "description": "One published file of the report, enriched with transient API download credentials. Its name, record count, size and checksum do not change when a link is reissued.", "properties": { "sequence": {"type": "integer", "minimum": 1, "description": "Part number of this file within the report, starting at 1. It is the final segment of the file name, and the highest sequence in the report equals fileCount."}, "name": {"type": "string", "pattern": "^NEXUS_CAMT054_[A-Za-z0-9._-]+_[0-9]{8}_v[1-9][0-9]*_[1-9][0-9]*\\.xml\\.gpg$", "description": "Published file name: NEXUS_CAMT054___v_.xml.gpg. The IPSO-ID, date, version and part segments must match participant, nexusDay, closeVersion and sequence.", "example": "NEXUS_CAMT054_IPSOMYKL_20260916_v1_1.xml.gpg"}, "records": {"type": "integer", "minimum": 0, "description": "Number of records in this file; includes zero-activity reports."}, "sizeBytes": {"type": "integer", "minimum": 1, "description": "Byte length of the exact protected delivered file, not the decrypted XML size."}, "checksums": {"$ref": "#/components/schemas/ReportChecksums"}, "url": {"type": "string", "format": "uri", "pattern": "^https://", "description": "Response-only signed URL bound to this exact file/version and authorised IPSO. Start the download before expiry; a started transfer may finish later. Never persist it as business data, log it, or forward an Operations OAuth token or RFC 9421 signature to its host. The download carries no RFC 9421 signature; verify the bytes against the SHA256 checksum in this signed manifest."}, "expiresAt": {"type": "string", "format": "date-time", "description": "Exclusive expiry instant, link issuance plus exactly 300 seconds. Not generatedAt plus 300 seconds and not report retention expiry. Response-only; a new link may have a new expiry without changing publication facts."} } }, "ReportProtection": { "type": "object", "additionalProperties": false, "required": ["algorithm", "keyId"], "description": "A cryptographic operation applied to the published file, naming the algorithm and the key the IPSO must use to verify or decrypt it.", "properties": { "algorithm": {"type": "string", "minLength": 1, "description": "Approved algorithm name."}, "keyId": {"type": "string", "minLength": 1, "description": "Identifier of the key used, so the IPSO can select the right key across a rotation."} } }, "ReportManifest": { "type": "object", "additionalProperties": false, "required": ["manifestVersion", "reportType", "participant", "nexusDay", "closeVersion", "generatedAt", "periodStart", "periodEnd", "dataAsOf", "fileCount", "totalRecords", "totals", "signature", "encryption", "files"], "description": "The manifest of a completely published report. This is the same manifest, with the same field names, that accompanies the file on SFTP; the API response adds only the per-file signed url and expiresAt, which exist for this response alone and are never stored. The reported period is the single Nexus Day named by nexusDay, and periodEnd is inclusive. fileCount equals the files length and the highest file sequence; totalRecords equals both the sum of files.records and the sum of the status totals. Enforce cross-field equality, real-calendar and day-boundary rules and filename identity server-side; JSON Schema alone does not express these arithmetic and cross-field invariants.", "properties": { "manifestVersion": {"type": "string", "const": "1.0", "description": "Version of the manifest structure, independent of closeVersion, the ISO message version and /v1."}, "reportType": {"type": "string", "const": "CAMT054"}, "participant": {"$ref": "#/components/schemas/Identifier", "description": "Reporting identifier of the authenticated IPSO, as used in the file's IPSO-ID segment. Derived from the trusted IPSO/environment binding; never a caller-selected participant filter."}, "nexusDay": {"$ref": "#/components/schemas/ReportDate", "description": "Reported Nexus Day in YYYYMMDD, corresponding to the requested date and its SGT day boundaries."}, "closeVersion": {"type": "integer", "minimum": 1, "description": "Version of the close for this Nexus Day. A correction is published as a higher closeVersion; always use the highest closeVersion available."}, "generatedAt": {"type": "string", "format": "date-time", "description": "Publication timestamp of this close version; unchanged when a signed link is reissued."}, "periodStart": {"type": "string", "format": "date-time", "description": "Start of the reported Nexus Day, 00:00:00 SGT."}, "periodEnd": {"type": "string", "format": "date-time", "description": "Inclusive end of the reported Nexus Day, 23:59:59 SGT."}, "dataAsOf": {"type": "string", "format": "date-time"}, "fileCount": {"type": "integer", "minimum": 1, "description": "Number of files in this report, equal to the files length and to the highest file sequence. A report is at least one file, including a zero-activity day; larger reports may be split across several files."}, "totalRecords": {"type": "integer", "minimum": 0, "description": "Equals the sum of files.records and the sum of the status totals; zero is valid for a published zero-activity report."}, "totals": {"type": "object", "additionalProperties": false, "required": ["ACCC", "RJCT", "PDNG", "BLCK"], "properties": {"ACCC": {"type": "integer", "minimum": 0}, "RJCT": {"type": "integer", "minimum": 0}, "PDNG": {"type": "integer", "minimum": 0}, "BLCK": {"type": "integer", "minimum": 0}}}, "signature": {"$ref": "#/components/schemas/ReportProtection", "description": "The Nexus signature over the report, which the IPSO must verify before loading the data."}, "encryption": {"$ref": "#/components/schemas/ReportProtection", "description": "The encryption applied to the report, identifying the key the IPSO decrypts with."}, "files": {"type": "array", "minItems": 1, "items": {"$ref": "#/components/schemas/ReportFile"}} } }, "ReportDownload": {"description": "The manifest of the latest published report for the requested Nexus Day, with a signed download link per file. A link is valid for exactly 300 seconds from issuance for initiation. Re-requesting an expired or interrupted link consumes a further retrieval allowance unit. Always use the highest closeVersion, verify the signature and the SHA-256 checksum, and decrypt with the key named in the manifest before loading the data.", "type": "object", "additionalProperties": false, "required": ["manifest"], "properties": {"manifest": {"$ref": "#/components/schemas/ReportManifest"}}}, "Error": { "type": "object", "additionalProperties": false, "required": ["statusCode", "reasonCode", "name", "description"], "description": "Payment Processing-compatible rejection envelope. RJCT concerns this API request, not a payment state. Reason code and name must match the defined pair. Description is PII-free and does not reveal unauthorised object existence.", "properties": {"statusCode": {"const": "RJCT"}, "reasonCode": {"type": "string"}, "name": {"type": "string"}, "description": {"type": "string", "minLength": 1}}, "oneOf": [ {"properties": {"reasonCode": {"const": "TE001"}, "name": {"const": "INVALID_REQUEST"}}}, {"properties": {"reasonCode": {"const": "TE099"}, "name": {"const": "INTERNAL_ERROR"}}}, {"properties": {"reasonCode": {"const": "AE001"}, "name": {"const": "AUTH_TOKEN_MISSING"}}}, {"properties": {"reasonCode": {"const": "AE002"}, "name": {"const": "AUTH_TOKEN_INVALID"}}}, {"properties": {"reasonCode": {"const": "AE003"}, "name": {"const": "MTLS_AUTH_FAILED"}}}, {"properties": {"reasonCode": {"const": "AE004"}, "name": {"const": "ACCESS_DENIED"}}}, {"properties": {"reasonCode": {"const": "AE005"}, "name": {"const": "MESSAGE_SIGNATURE_INVALID"}}}, {"properties": {"reasonCode": {"const": "BE901"}, "name": {"const": "REPORT_NOT_FOUND"}}}, {"properties": {"reasonCode": {"const": "BE902"}, "name": {"const": "REPORT_NOT_READY"}}}, {"properties": {"reasonCode": {"const": "BE903"}, "name": {"const": "REPORT_OUTSIDE_RETRIEVAL_WINDOW"}}}, {"properties": {"reasonCode": {"const": "BE904"}, "name": {"const": "TRANSACTION_NOT_FOUND"}}}, {"properties": {"reasonCode": {"const": "BE905"}, "name": {"const": "RANGE_TOO_WIDE"}}}, {"properties": {"reasonCode": {"const": "BE906"}, "name": {"const": "QUERY_TOO_LARGE"}}}, {"properties": {"reasonCode": {"const": "BE907"}, "name": {"const": "RESULT_TOO_LARGE"}}}, {"properties": {"reasonCode": {"const": "BE908"}, "name": {"const": "RATE_LIMIT_EXCEEDED"}}}, {"properties": {"reasonCode": {"const": "BE909"}, "name": {"const": "CONCURRENCY_LIMIT_EXCEEDED"}}}, {"properties": {"reasonCode": {"const": "BE910"}, "name": {"const": "DAILY_ALLOWANCE_EXCEEDED"}}}, {"properties": {"reasonCode": {"const": "BE911"}, "name": {"const": "IDENTICAL_QUERY_TOO_SOON"}}}, {"properties": {"reasonCode": {"const": "BE912"}, "name": {"const": "IDEMPOTENCY_KEY_CONFLICT"}}} ] } }, "responses": { "ServiceRequestBadRequest": {"description": "400 TE001 INVALID_REQUEST. Malformed/duplicate-key JSON, a missing or invalid Idempotency-Key, missing/blank fields, an unsupported requestCode, category, payloadVersion or recipient-type combination, a category that does not match the selected requestCode, invalid IPSOId or FXPId syntax, unknown fields, an applicantType inconsistent with the selected requestCode, an invalid UETR, billing period or timestamp, or prohibited content. Do not echo rejected content. Correct the request; no new idempotency reservation or business-allowance unit is consumed.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"const": "INVALID_REQUEST"}}}]}, "examples": {"unsupportedProfile": {"value": {"statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "Select a supported ticket type, payload version and recipient combination."}}, "unexpectedPayloadField": {"value": {"statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "The payload contains a field not permitted by the selected profile."}}}}}}, "ServiceRequestForbidden": {"description": "403 AE004 ACCESS_DENIED. The authenticated caller lacks the create scope or profile entitlement, or the recipient is not eligible. Use the same response for unknown, inactive, self, cross-environment and unauthorised recipient IPSOs; do not reveal target existence or onboarding status. No acceptance or new key reservation.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"const": "ACCESS_DENIED"}}}]}, "example": {"statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "The caller is not permitted to submit this request to the selected recipient."}}}}, "ServiceRequestIdempotencyConflict": {"description": "409 BE912 IDEMPOTENCY_KEY_CONFLICT. This submitting IPSO/environment/operation has already accepted different content under the supplied key. Return no original body, recipient or receipt information. Recover the original submission; a different key is only for a genuinely new intended request.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"const": "IDEMPOTENCY_KEY_CONFLICT"}}}]}, "example": {"statusCode": "RJCT", "reasonCode": "BE912", "name": "IDEMPOTENCY_KEY_CONFLICT", "description": "The idempotency key is already bound to different request content."}}}}, "ServiceRequestThrottled": {"description": "429 BE908 RATE_LIMIT_EXCEEDED, BE909 CONCURRENCY_LIMIT_EXCEEDED or BE910 DAILY_ALLOWANCE_EXCEEDED under the published intake policy. An exact replay consumes no new-submission unit but remains subject to transport rate and concurrency controls. No new acceptance or key reservation occurs. Honour the mandatory positive Retry-After and retry with the same key and body.", "headers": {"Retry-After": {"$ref": "#/components/headers/RetryAfter"}}, "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"enum": ["RATE_LIMIT_EXCEEDED", "CONCURRENCY_LIMIT_EXCEEDED", "DAILY_ALLOWANCE_EXCEEDED"]}}}]}, "example": {"statusCode": "RJCT", "reasonCode": "BE908", "name": "RATE_LIMIT_EXCEEDED", "description": "The IPSO request-intake rate is exhausted. Honour Retry-After."}}}}, "ServiceRequestInternalError": {"description": "500 TE099 INTERNAL_ERROR. Acceptance may be uncertain to the caller. Retry the same key and unchanged body with bounded backoff inside the published replay window; never create a fresh key merely because the receipt was lost.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"const": "INTERNAL_ERROR"}}}]}, "example": {"statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "The request-intake outcome could not be confirmed. Retry with the same idempotency key."}}}}, "ServiceRequestUnavailable": {"description": "503 native response without a Nexus JSON-body guarantee. Durable intake, idempotency, quota or required authorisation state cannot be safely established. Fail closed; never return 202 without durable commit. Retry an uncertain request with the same key/body and bounded backoff. A ServiceNow outage alone does not reject already durable intake; accepted work remains in monitored retry/recovery, subject to published admission/backpressure limits.", "headers": {"Retry-After": {"description": "Optional positive delay-seconds for transient unavailability. Honour it before retrying with the same key/body.", "schema": {"type": "integer", "minimum": 1}, "example": 60}}}, "BadRequest": {"description": "400 TE001 INVALID_REQUEST. Reject malformed, repeated/unknown parameters, unsupported query modes, invalid dates or identifiers. Do not retry unchanged.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"const": "INVALID_REQUEST"}}}]}, "example": {"statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "The request does not satisfy the reporting query contract."}}}}, "QueryBadRequest": {"description": "400 BE905 RANGE_TOO_WIDE for an otherwise valid range above 31 inclusive Nexus Days. TE001 INVALID_REQUEST covers missing dates, invalid/reversed/future/out-of-retention dates, unsupported status values, pageSize outside 1..2500, invalid/expired/cross-scope cursors, cursor mixed with filters and unknown or repeated parameters. Narrow or correct the request; never retry unchanged.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"enum": ["INVALID_REQUEST", "RANGE_TOO_WIDE"]}}}]}, "examples": {"rangeTooWide": {"value": {"statusCode": "RJCT", "reasonCode": "BE905", "name": "RANGE_TOO_WIDE", "description": "Select at most 31 inclusive Nexus Days."}}, "missingDates": {"value": {"statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "Every new feed query requires fromDate and toDate; status is an optional filter."}}, "pageTooLarge": {"value": {"statusCode": "RJCT", "reasonCode": "TE001", "name": "INVALID_REQUEST", "description": "pageSize must be between 1 and 2500."}}}}}}, "Unauthorized": {"description": "401 AE001 AUTH_TOKEN_MISSING, AE002 AUTH_TOKEN_INVALID, AE003 MTLS_AUTH_FAILED or AE005 MESSAGE_SIGNATURE_INVALID. Includes wrong issuer or audience, certificate-binding mismatch, and presenting an Operations reporting token to Track and Trace or a payment token to a reporting operation. AE005 applies to every operation: the RFC 9421 signature is missing, malformed, does not cover the required components or does not verify, the keyid is unknown, expired, revoked or registered for the other (payment or Operations) path, created/expires is outside the tolerance window, or the Content-Digest does not match the body. A TLS handshake rejection may have no HTTP response.", "headers": {"WWW-Authenticate": {"schema": {"type": "string"}, "example": "Bearer error=\"invalid_token\""}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "examples": {"AUTH_TOKEN_INVALID": {"summary": "Token rejected", "value": {"statusCode": "RJCT", "reasonCode": "AE002", "name": "AUTH_TOKEN_INVALID", "description": "A valid Operations access token is required."}}, "MESSAGE_SIGNATURE_INVALID": {"summary": "Message signature rejected", "value": {"statusCode": "RJCT", "reasonCode": "AE005", "name": "MESSAGE_SIGNATURE_INVALID", "description": "The RFC 9421 message signature (Signature-Input, Signature) was missing or malformed, did not cover the components required by the Nexus profile, or did not verify (rsa-pss-sha512) against the sender's registered signing public key for this API path; the keyid was missing, unknown, expired or revoked; created/expires fell outside the tolerance window; or the Content-Digest did not match the request body."}}}}}}, "Forbidden": {"description": "403 AE004 ACCESS_DENIED. Valid credentials lack the operation scope, active IPSO identity or environment entitlement. Machine scopes and human Portal grants are independent; no participant identity supplied in a query can override the credential-derived scope.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"statusCode": "RJCT", "reasonCode": "AE004", "name": "ACCESS_DENIED", "description": "Access to this reporting capability is not permitted."}}}}, "ReportMissing": {"description": "404 BE901 REPORT_NOT_FOUND. No published file in the eligible window; not evidence of zero activity, because a Nexus Day with no transactions is still published and returns 200 with its manifest. For a date inside the eligible window after 01:00 SGT this indicates a Nexus-side publication failure: raise a Service Desk ticket.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"statusCode": "RJCT", "reasonCode": "BE901", "name": "REPORT_NOT_FOUND", "description": "No published report is available for the requested date."}}}}, "ReportPending": {"description": "409 BE902 REPORT_NOT_READY. Publication for the requested Nexus Day is not complete. The attempt consumes no retrieval allowance unit; repeat requests while the report is not ready are limited to twice per minute and must wait at least the mandatory Retry-After, which points towards the expected publication time for that Nexus Day. Raise a Service Desk ticket if the report is still not ready after 01:00 SGT.", "headers": {"Retry-After": {"$ref": "#/components/headers/RetryAfter"}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"statusCode": "RJCT", "reasonCode": "BE902", "name": "REPORT_NOT_READY", "description": "Report publication is not complete."}}}}, "OutsideWindow": {"description": "410 BE903 REPORT_OUTSIDE_RETRIEVAL_WINDOW. Self-service eligibility has expired; this is not necessarily the end of storage. Request retained files through the Service Desk.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"statusCode": "RJCT", "reasonCode": "BE903", "name": "REPORT_OUTSIDE_RETRIEVAL_WINDOW", "description": "Request the retained report through the Service Desk."}}}}, "TransactionMissing": {"description": "404 BE904 TRANSACTION_NOT_FOUND. Identical for absent, outside-retention and unauthorised UETRs.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"statusCode": "RJCT", "reasonCode": "BE904", "name": "TRANSACTION_NOT_FOUND", "description": "No transaction is available for this enquiry."}}}}, "QueryGuardrailExceeded": {"description": "422 BE906 QUERY_TOO_LARGE when the bounded query exceeds the published execution or scan-cost guard, or BE907 RESULT_TOO_LARGE when the total logical result exceeds the published row or byte guard. The 2,500 page maximum is not a total-result threshold. Narrow the range or add filters. Never return a truncated success or continue an invalidated partial result as complete.", "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"enum": ["QUERY_TOO_LARGE", "RESULT_TOO_LARGE"]}}}]}, "examples": {"queryTooLarge": {"value": {"statusCode": "RJCT", "reasonCode": "BE906", "name": "QUERY_TOO_LARGE", "description": "The query exceeds the published execution guard. Narrow the range or add filters."}}, "resultTooLarge": {"value": {"statusCode": "RJCT", "reasonCode": "BE907", "name": "RESULT_TOO_LARGE", "description": "The logical result exceeds the published result guard. Narrow the range or add filters."}}}}}}, "RateLimited": {"description": "429 BE908 RATE_LIMIT_EXCEEDED. The IPSO's published request rate for this capability is exhausted; for Track and Trace the rate is shared between the screen and API callers. Retry-After is mandatory; wait as indicated and use bounded exponential backoff with jitter for repeated failures.", "headers": {"Retry-After": {"$ref": "#/components/headers/RetryAfter"}}, "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"const": "RATE_LIMIT_EXCEEDED"}}}]}, "example": {"statusCode": "RJCT", "reasonCode": "BE908", "name": "RATE_LIMIT_EXCEEDED", "description": "The IPSO request rate is exhausted. Honour Retry-After."}}}}, "ReportThrottled": {"description": "429 BE908 RATE_LIMIT_EXCEEDED or BE910 DAILY_ALLOWANCE_EXCEEDED. RATE_LIMIT_EXCEEDED applies to repeat requests for a report that is not ready, which are limited to twice per minute. DAILY_ALLOWANCE_EXCEEDED means the IPSO's retrieval allowance for the current Nexus Day is exhausted, and its mandatory Retry-After is the rounded-up seconds until the next daily reset. A 409 not-ready response consumes none of that allowance, and repeated link requests do not bypass it.", "headers": {"Retry-After": {"$ref": "#/components/headers/RetryAfter"}}, "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"enum": ["RATE_LIMIT_EXCEEDED", "DAILY_ALLOWANCE_EXCEEDED"]}}}]}, "examples": {"notReadyRate": {"value": {"statusCode": "RJCT", "reasonCode": "BE908", "name": "RATE_LIMIT_EXCEEDED", "description": "The not-ready request rate is exhausted. Honour Retry-After."}}, "daily": {"value": {"statusCode": "RJCT", "reasonCode": "BE910", "name": "DAILY_ALLOWANCE_EXCEEDED", "description": "The IPSO's daily retrieval allowance is exhausted. Wait until the next daily reset."}}}}}}, "FeedThrottled": {"description": "429 BE908 RATE_LIMIT_EXCEEDED (new logical queries), BE909 CONCURRENCY_LIMIT_EXCEEDED (in-flight HTTP requests, including pages), BE910 DAILY_ALLOWANCE_EXCEEDED (logical queries for the Nexus Day), or BE911 IDENTICAL_QUERY_TOO_SOON (the same normalised query re-admitted inside its cooldown). Valid cursor continuation is subject only to concurrency, not the other three counters. Every rejection includes Retry-After; where multiple controls block, the longest known blocking delay is returned. A rejected attempt neither extends a cooldown nor consumes allowance.", "headers": {"Retry-After": {"$ref": "#/components/headers/RetryAfter"}}, "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/Error"}, {"properties": {"name": {"enum": ["RATE_LIMIT_EXCEEDED", "CONCURRENCY_LIMIT_EXCEEDED", "DAILY_ALLOWANCE_EXCEEDED", "IDENTICAL_QUERY_TOO_SOON"]}}}]}, "examples": {"rate": {"value": {"statusCode": "RJCT", "reasonCode": "BE908", "name": "RATE_LIMIT_EXCEEDED", "description": "The IPSO's new-query rate is exhausted. Honour Retry-After."}}, "concurrency": {"value": {"statusCode": "RJCT", "reasonCode": "BE909", "name": "CONCURRENCY_LIMIT_EXCEEDED", "description": "The IPSO already has the maximum number of requests in flight."}}, "daily": {"value": {"statusCode": "RJCT", "reasonCode": "BE910", "name": "DAILY_ALLOWANCE_EXCEEDED", "description": "The IPSO's logical-query allowance for this Nexus Day is exhausted; valid cursor continuations remain permitted."}}, "identical": {"value": {"statusCode": "RJCT", "reasonCode": "BE911", "name": "IDENTICAL_QUERY_TOO_SOON", "description": "Wait until the identical-query cooldown expires before starting it again."}}}}}}, "InternalError": {"description": "500 TE099 INTERNAL_ERROR. Use bounded backoff within the applicable usage controls; contact the Service Desk if persistent.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": {"statusCode": "RJCT", "reasonCode": "TE099", "name": "INTERNAL_ERROR", "description": "The reporting request could not be completed."}}}}, "Unavailable": {"description": "503 native response: source/publication/quota service unavailable or token validation cannot safely complete. Fail closed, never return false empty/ready data or bypass limits. Retry only within published limits.", "headers": {"Retry-After": {"description": "Optional suggested positive delay-seconds for transient unavailability; when supplied, honour it within the usage controls.", "schema": {"type": "integer", "minimum": 1}, "example": 60}}}, "PerimeterError": {"description": "Native HTTP perimeter response, including 405 (Allow header), 502 and 504. No Nexus JSON error-body guarantee for these failures. Per-IPSO policy 429 responses use the explicit typed contract. Bounded retry only for transient failures."} } } }