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.
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 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.
- : Create supported ServiceNow tickets addressed to NGO, NGP, an authorised counterparty IPSO or a selected FXP; grants no reporting, fulfilment or approval rights
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.
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.
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.
bc689fb6-c2a0-4b9a-a3c7-41cc4be6ba0bPattern: ^[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}$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.
nexus=("@method" "@authority" "@path" "@query" "content-type" "content-digest");created=1786339201;expires=1786339501;keyid="NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs";alg="rsa-pss-sha512";tag="nexus-v1"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"$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.
nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:Pattern: ^nexus=:[A-Za-z0-9+/]+={0,2}:$RFC 9530 digest of the exact request body bytes as sent: sha-512=:<standard base64 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.
sha-512=:3Sd3sG3WdBHVvvBdDh960Fgte6DbbpV+0NCVwRGakd3zwCpydFQv5xs80UQg3u7JtC+mLXzHybSsjJUvN0Cf8g==:Pattern: ^sha-512=:[A-Za-z0-9+/]{86}==:$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.
Durable NGO acceptance receipt, also returned unchanged for an authorised exact replay. Acceptance is not a ServiceNow creation, delivery or fulfilment acknowledgement.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
POST /v1/service-requests HTTP/1.1
Host: prod.operations.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Signature-Input: text
Signature: text
Content-Digest: text
Content-Type: application/json
Accept: */*
Content-Length: 350
{
"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"
}
}{
"requestId": "8b7088e0-2f5c-4cb8-9ec9-6c30b38a42d1",
"status": "ACCEPTED",
"acceptedAt": "2026-10-02T08:15:00Z"
}Last updated
