> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/nexus-operation-apis/service-requests.md). # Service Requests 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. #### Service catalog: category and item The 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. NGO operates the intake in every case; the recipient column names the party that owns fulfilment. | Primary catalog | Sub-catalog item | Category | Request code | Recipient | Description | Primary IPSO role | | ---------------------------------- | --------------------------------------------------- | -------------------------------------- | --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | 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 | | Dispute & Resolution Management | Raise Formal Dispute — 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 | | Dispute & Resolution Management | Raise Formal Dispute — 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 | | Dispute & Resolution Management | Raise Formal Dispute — 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 | | 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 | | 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 | | 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 | #### Scope boundaries Payment 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. A 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. Catalog 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. #### Contract evolution The 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. ## Create a ServiceNow ticket > 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.\ > \ > Use 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.\ > \ > Send 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.\ > \ > Accepting 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.\ > \ > 202 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.\ > \ > Track 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. ```json {"openapi":"3.1.0","info":{"title":"Nexus Operations IPSO API","version":"0.4.0"},"tags":[{"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 — 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 — 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 — 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."}],"servers":[{"url":"https://{environment}.operations.nexus.net","description":"Operations reporting endpoint.","variables":{"environment":{"default":"prod","enum":["pat","prod"],"description":"Deployment environment subdomain."}}}],"security":[{"nexusOAuth":["operations.service-requests.create"],"mutualTLS":[]}],"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"}}}}},"parameters":{"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}$"}},"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\"$"}},"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}:$"}},"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}==:$"}}},"schemas":{"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"}}}]},"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."},"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."},"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."},"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."},"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."},"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."},"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."},"Identifier":{"type":"string","minLength":1,"maxLength":128,"description":"Source-owned institutional/operational identifier, not customer PII."},"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."},"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."},"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."},"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}$"},"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."},"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."},"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."},"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."},"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."},"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."},"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."},"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."},"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"}}}]}},"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}}},"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"}}}]}}}},"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"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"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"}}}]}}}},"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"}}}]}}}},"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"]}}}]}}}},"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"}}}]}}}},"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}}}},"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."}}},"paths":{"/v1/service-requests":{"post":{"tags":["ServiceRequests"],"operationId":"submitServiceRequest","summary":"Create a ServiceNow ticket","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.","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"}}}},"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"}}}},"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"}}}}}} ```