---
title: "Submit ISO 20022 message"
method: POST
path: "/iso20022/{messagePath}"
tags: ["ISO 20022"]
---

# Submit ISO 20022 message

`POST /iso20022/{messagePath}`

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.

## Path parameters

- `messagePath` 'pacs.008' | 'pacs.002' | 'pacs.028' | 'acmt.023' | 'acmt.024' | 'camt.054' | 'camt.056' | 'camt.029' | 'admi.002' | 'admi.004', required

## Response `202`

Accepted. Technical acknowledgement confirming receipt and schema validation only; the business response follows asynchronously as an ISO 20022 message to the registered endpoint.

- TechnicalAckDto — Synchronous technical acknowledgement for ISO 20022 message ingress. Confirms receipt and schema validation only; carries no business decision.
  - `uetr` string — Unique End-to-end Transaction Reference echoed from the submitted message, where present.
  - `messageType` 'pacs.008' | 'pacs.002' | 'pacs.028' | 'acmt.023' | 'acmt.024' | 'camt.054' | 'camt.056' | 'camt.029' | 'admi.002' | 'admi.004', required — ISO 20022 message type of the submitted message.
  - `msgId` string — 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.
  - `receivedAt` string, date-time, required — Timestamp at which the message was received by the gateway.
  - `status` 'RECEIVED' | 'REJECTED', required — Technical acceptance status. RECEIVED confirms schema-valid receipt; the business outcome follows asynchronously.
  - `ackCode` string — Technical acknowledgement code.

## Other responses

- `400` — Message failed validation. Applicable reason codes: TE001 INVALID_REQUEST, TE002 INVALID_XML.
- `401` — Authentication failed. Applicable reason codes: AE001 AUTH_TOKEN_MISSING, AE002 AUTH_TOKEN_INVALID, AE003 MTLS_AUTH_FAILED.
- `403` — Authorization failed. The token is valid but its OAuth2 scopes do not grant access to this endpoint or corridor. Reason code AE004 ACCESS_DENIED.
- `404` — Unsupported message type.
- `409` — 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` — The request body exceeds the maximum size allowed by the API gateway. Returned by the gateway and carries no structured Nexus body.
- `429` — Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.
- `500` — An unhandled exception or infrastructure failure occurred. Reason code TE099 INTERNAL_ERROR. The caller may retry with exponential backoff.

---

[API](https://skmtc.net/nexusglobalpayments/apis/nexus-apis.md) · [All operations](https://skmtc.net/nexusglobalpayments/apis/nexus-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nexusglobalpayments/nexus-apis/revisions/b3e625f21841/schema)