> 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/apis/iso-20022-messages.md).

# ISO 20022 Messages

{% hint style="info" %}
ISO 20022 messages are submitted to Nexus via asynchronous API.

The ISO 20022 XML message itself will be included in full in the message body.

The Source IPSO will also define an endpoint to which Nexus should send the resulting response (ie when submitting acmt.023, the Source IPSO must also define the acmt024Endpoint to which Nexus should send the acmt.024 response).
{% endhint %}

## Submit ISO 20022 message

> Accepts an ISO 20022 message in XML format, prepared according to the Nexus Message Usage Guidelines. The \`messagePath\` path parameter selects the message type:\
> \
> \- \`pacs.008\` — FI to FI Customer Credit Transfer\
> \- \`pacs.002\` — FI to FI Payment Status Report\
> \- \`pacs.028\` — FI to FI Payment Status Request\
> \- \`acmt.023\` — Identification Verification Request\
> \- \`acmt.024\` — Identification Verification Report\
> \- \`camt.054\` — Bank to Customer Debit Credit Notification\
> \- \`camt.056\` — FI to FI Payment Cancellation Request\
> \- \`camt.029\` — Resolution of Investigation\
> \- \`admi.002\` — Message Reject\
> \- \`admi.004\` — System Event Notification\
> \
> The synchronous 202 Accepted response is a technical acknowledgement (application/json) confirming receipt and schema validation only. The business response is delivered asynchronously as an ISO 20022 message to the participant's registered endpoint (e.g. pacs.008 → asynchronous pacs.002; acmt.023 → acmt.024). Unsupported message types return 404 with an ErrorResultDto body.

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TechnicalAckDto":{"type":"object","description":"Synchronous technical acknowledgement for ISO 20022 message ingress. Confirms receipt and schema validation only; carries no business decision.","properties":{"uetr":{"type":"string","description":"Unique End-to-end Transaction Reference echoed from the submitted message, where present."},"messageType":{"type":"string","enum":["pacs.008","pacs.002","pacs.028","acmt.023","acmt.024","camt.054","camt.056","camt.029","admi.002","admi.004"],"description":"ISO 20022 message type of the submitted message."},"msgId":{"type":"string","description":"Nexus Message Identification (MsgId). Point to point reference, as assigned by the instructing party, and sent to the next party in the chain to unambiguously identify the message. Set by the Source IPSO. Fixed 35 character maximum structure: positions 1 to 8 carry the date as YYYYMMDD; position 9 carries the fixed value N identifying a Nexus transaction; position 10 carries the fixed value X reserved for future use; positions 11 to 14 carry the message type and subtype, for example PS08 for pacs.008; position 15 carries an alphanumeric value identifying the purpose of the message usage, where 1 is the default usage purpose for payment messages; positions 16 to 23 carry an 8 character sequence generated by the message sender, for example 23GH2345; positions 24 to 35 carry the organisation or PSP identifier, a BIC or local clearing member id such as SBININBBXXX or 78667, with no leading or trailing padding when shorter than 12 characters.","pattern":"^[0-9]{8}NX[A-Z0-9]{4}[A-Z0-9][A-Z0-9]{8}[A-Z0-9]{1,12}$","minLength":24,"maxLength":35},"receivedAt":{"type":"string","format":"date-time","description":"Timestamp at which the message was received by the gateway."},"status":{"type":"string","enum":["RECEIVED","REJECTED"],"description":"Technical acceptance status. RECEIVED confirms schema-valid receipt; the business outcome follows asynchronously."},"ackCode":{"type":"string","description":"Technical acknowledgement code."}},"required":["messageType","receivedAt","status"]},"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/iso20022/{messagePath}":{"post":{"summary":"Submit ISO 20022 message","description":"Accepts an ISO 20022 message in XML format, prepared according to the Nexus Message Usage Guidelines. The `messagePath` path parameter selects the message type:\n\n- `pacs.008` — FI to FI Customer Credit Transfer\n- `pacs.002` — FI to FI Payment Status Report\n- `pacs.028` — FI to FI Payment Status Request\n- `acmt.023` — Identification Verification Request\n- `acmt.024` — Identification Verification Report\n- `camt.054` — Bank to Customer Debit Credit Notification\n- `camt.056` — FI to FI Payment Cancellation Request\n- `camt.029` — Resolution of Investigation\n- `admi.002` — Message Reject\n- `admi.004` — System Event Notification\n\nThe synchronous 202 Accepted response is a technical acknowledgement (application/json) confirming receipt and schema validation only. The business response is delivered asynchronously as an ISO 20022 message to the participant's registered endpoint (e.g. pacs.008 → asynchronous pacs.002; acmt.023 → acmt.024). Unsupported message types return 404 with an ErrorResultDto body.","operationId":"submitIso20022Message","tags":["ISO 20022"],"parameters":[{"name":"messagePath","in":"path","required":true,"description":"ISO 20022 message type identifier.","schema":{"type":"string","enum":["pacs.008","pacs.002","pacs.028","acmt.023","acmt.024","camt.054","camt.056","camt.029","admi.002","admi.004"]}}],"requestBody":{"required":true,"content":{"application/xml":{"schema":{"type":"string","description":"ISO 20022 XML message conforming to the Nexus Message Usage Guidelines for the selected message type."}}}},"responses":{"202":{"description":"Accepted. Technical acknowledgement confirming receipt and schema validation only; the business response follows asynchronously as an ISO 20022 message to the registered endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TechnicalAckDto"}}}},"400":{"description":"Message failed validation. Applicable reason codes: TE001 INVALID_REQUEST, TE002 INVALID_XML.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Authentication failed. Applicable reason codes: AE001 AUTH_TOKEN_MISSING, AE002 AUTH_TOKEN_INVALID, AE003 MTLS_AUTH_FAILED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Authorization failed. The token is valid but its OAuth2 scopes do not grant access to this endpoint or corridor. Reason code AE004 ACCESS_DENIED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"404":{"description":"Unsupported message type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"409":{"description":"Perimeter idempotency key conflict detected at the API gateway. The same request, meaning the same idempotency key and business identifiers, was already accepted and is in flight. Returned by the gateway and carries no structured Nexus body. Do not retry. Treat the original submission as accepted; if the business outcome is unknown, use the pacs.028 Payment Status Request. A business level duplicate pacs.008 is answered with a negative pacs.002 with reason DUPL, not with this status."},"413":{"description":"The request body exceeds the maximum size allowed by the API gateway. Returned by the gateway and carries no structured Nexus body."},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"An unhandled exception or infrastructure failure occurred. Reason code TE099 INTERNAL_ERROR. The caller may retry with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}}}}}}
```