> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# pacs.008 format

> Understand the pacs.008 XML document Meridian expects you to Base64-encode and submit to the Payout Origination API.

Use this page to understand the message document you send to the Payout Origination API before you Base64-encode it.

<Info>
  Use `pacs008` as the `{format}` path parameter when submitting this message type:
  `POST /v1/payout-origination/pacs008`
</Info>

Meridian accepts `pacs.008.*` as one of the supported payout origination formats. You must submit the full original ISO 20022 XML document as a single opaque payload. Do not split the message into API fields or convert it into another structure.

## Meridian intake requirements

| Item               | Requirement                                                                   |
| :----------------- | :---------------------------------------------------------------------------- |
| Message family     | `pacs.008.*`                                                                  |
| Document format    | ISO 20022 XML                                                                 |
| Submission model   | Base64-encode the full message document and send it as the request body       |
| Content type       | `text/plain`                                                                  |
| Transaction blocks | Exactly one `CdtTrfTxInf` block per submitted message                         |
| Transformations    | Do not flatten, normalize, or partially serialize the message before encoding |

## What Meridian means by full pacs.008

Meridian expects the complete business message content for the payment instruction you are submitting.

That means you should preserve:

* the original XML structure
* the version-specific namespace
* the element hierarchy
* the values and formatting used in the original message

The API treats the Base64 body as an opaque artifact at intake. Meridian does not expect you to map `pacs.008` fields into separate JSON properties.

## High-level document structure

A `pacs.008` message is an ISO 20022 customer credit transfer instruction. The exact variant depends on the message version you use, but the structure is typically organized like this:

```xml theme={null}
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.xx">
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      ...
    </GrpHdr>
    <CdtTrfTxInf>
      ...
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>
```

In most integrations:

* `Document` is the XML root element
* `FIToFICstmrCdtTrf` contains the credit transfer message
* `GrpHdr` contains message-level metadata
* `CdtTrfTxInf` contains the payment transaction details

Depending on the `pacs.008` version and network rules, the document may include one or more transaction blocks and additional optional elements.

For Meridian Payout Origination, the submitted message must contain exactly one `CdtTrfTxInf` block. Messages with multiple transaction blocks are outside the documented contract for this API.

## Common sections

The table below describes the sections most integrators will recognize in a `pacs.008` document. Exact child elements vary by schema version and implementation profile.

| Section               | Purpose                                                                                 |
| :-------------------- | :-------------------------------------------------------------------------------------- |
| `GrpHdr`              | Message-level identifiers, creation time, settlement information, and transaction count |
| `PmtId`               | End-to-end and transaction reference identifiers                                        |
| `IntrBkSttlmAmt`      | Interbank settlement amount and currency                                                |
| `IntrBkSttlmDt`       | Settlement date                                                                         |
| `Dbtr` and `DbtrAcct` | Debtor party and account information                                                    |
| `DbtrAgt`             | Debtor agent or sending institution                                                     |
| `CdtrAgt`             | Creditor agent or receiving institution                                                 |
| `Cdtr` and `CdtrAcct` | Creditor party and account information                                                  |
| `RmtInf`              | Remittance information                                                                  |
| `Purp` or `CtgyPurp`  | Payment purpose or category purpose when applicable                                     |

## Settlement currency

The `Ccy` attribute on `IntrBkSttlmAmt` in your submitted message determines the payout currency and flows through to `amounts.debit.currency` and `amounts.credit.currency` in the transaction model.

```xml theme={null}
<IntrBkSttlmAmt Ccy="USD">4800.00</IntrBkSttlmAmt>
```

| Currency | Status      |
| :------- | :---------- |
| `USD`    | Supported   |
| `EUR`    | Coming soon |
| `GBP`    | Coming soon |
| `AUD`    | Coming soon |

## Practical expectations

When you prepare a message for Meridian:

* send a complete `pacs.008` message document, not a fragment
* preserve the schema namespace that matches your chosen `pacs.008` version
* preserve the original identifiers used for the payment instruction
* include exactly one `CdtTrfTxInf` block in each submitted message
* keep the XML as the source artifact that you encode and submit
* validate the message against your own network and schema rules before encoding

If your implementation profile requires additional envelopes or headers outside the `Document` payload, align that packaging with Meridian during onboarding. The ingestion endpoint itself expects the encoded payload to contain the message document you want processed.

## Example skeleton

This example shows the shape Meridian expects at a document level. It is intentionally abbreviated and not a complete, schema-valid payment message.

```xml theme={null}
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.xx">
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>20260407-000123</MsgId>
      <CreDtTm>2026-04-07T20:11:40Z</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <SttlmInf>
        <SttlmMtd>CLRG</SttlmMtd>
      </SttlmInf>
    </GrpHdr>
    <CdtTrfTxInf>
      <PmtId>
        <InstrId>ABC-12345</InstrId>
        <EndToEndId>E2E-12345</EndToEndId>
        <TxId>TX-12345</TxId>
      </PmtId>
      <IntrBkSttlmAmt Ccy="USD">1250.00</IntrBkSttlmAmt>
      <IntrBkSttlmDt>2026-04-08</IntrBkSttlmDt>
      <Dbtr>
        <Nm>Sender Name</Nm>
      </Dbtr>
      <DbtrAgt>
        <FinInstnId>
          <BICFI>AAAAUS33XXX</BICFI>
        </FinInstnId>
      </DbtrAgt>
      <CdtrAgt>
        <FinInstnId>
          <BICFI>BBBBGB22XXX</BICFI>
        </FinInstnId>
      </CdtrAgt>
      <Cdtr>
        <Nm>Receiver Name</Nm>
      </Cdtr>
      <RmtInf>
        <Ustrd>Invoice 100045</Ustrd>
      </RmtInf>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>
```

## Before you submit

Before calling `POST /v1/payout-origination/pacs008`:

1. Build or receive the complete `pacs.008` message document.
2. Validate the XML and business content in your own system.
3. Base64-encode that message document.
4. Send the encoded payload to Meridian with HMAC authentication headers and a separate `Idempotency-Key` header.

## Transaction model mapping

Use this section to understand how Meridian maps a submitted `pacs.008` message into the internal transaction model that `GET /v1/transactions` and `GET /v1/transactions/{id}` expose.

The read APIs return Meridian's internal transaction model, not the original XML. Each submitted message must contain exactly one `CdtTrfTxInf` block.

### Mapping table

| Transaction field                                 | pacs.008 source                      | Notes                                                                                            |
| :------------------------------------------------ | :----------------------------------- | :----------------------------------------------------------------------------------------------- |
| `messageId`                                       | `GrpHdr/MsgId`                       | Meridian uses the message identifier from the submitted `pacs.008` as the message correlation ID |
| `externalId`                                      | `CdtTrfTxInf/PmtId/TxId`             | This is the primary business reference exposed as `externalId`                                   |
| `amounts.debit.amount`                            | `CdtTrfTxInf/IntrBkSttlmAmt`         | Uses the numeric value from the interbank settlement amount                                      |
| `amounts.debit.currency`                          | `CdtTrfTxInf/IntrBkSttlmAmt/@Ccy`    | Uses the currency attribute from the interbank settlement amount                                 |
| `amounts.credit.amount`                           | `CdtTrfTxInf/IntrBkSttlmAmt`         | Currently mirrors the same settlement amount                                                     |
| `amounts.credit.currency`                         | `CdtTrfTxInf/IntrBkSttlmAmt/@Ccy`    | Currently mirrors the same settlement currency                                                   |
| `debitInstrument.originator.displayName`          | `CdtTrfTxInf/Dbtr/Nm`                | Debtor name                                                                                      |
| `debitInstrument.originator.accountNumber`        | `CdtTrfTxInf/DbtrAcct/...`           | Use the debtor account identifier Meridian receives in the message                               |
| `creditInstrument.beneficiaryAccount.displayName` | `CdtTrfTxInf/Cdtr/Nm`                | Creditor name                                                                                    |
| `creditInstrument.beneficiaryAccount.id`          | `CdtTrfTxInf/CdtrAcct/...`           | Use the creditor account identifier Meridian receives in the message                             |
| `creditInstrument.beneficiaryAccount.currency`    | `CdtTrfTxInf/IntrBkSttlmAmt/@Ccy`    | The current documented example uses the settlement currency                                      |
| `source.type`                                     | Internal value `external_submission` | Current documented behavior for pacs.008-ingested transactions                                   |

### Internal fields

These transaction fields are internal Meridian fields and are not sourced directly from the `pacs.008` payload:

* `status`
* `statusReason`
* `createdAt`
* `updatedAt`
* `relatedTransactionId`

### Example mapping

Given this `pacs.008` fragment:

```xml theme={null}
<GrpHdr>
  <MsgId>20260407-000123</MsgId>
</GrpHdr>
<CdtTrfTxInf>
  <PmtId>
    <InstrId>ABC-12345</InstrId>
    <EndToEndId>E2E-12345</EndToEndId>
    <TxId>TX-12345</TxId>
  </PmtId>
  <IntrBkSttlmAmt Ccy="USD">1250.00</IntrBkSttlmAmt>
  <Dbtr>
    <Nm>Sender Name</Nm>
  </Dbtr>
  <DbtrAcct>
    <Id>
      <Othr>
        <Id>123456789</Id>
      </Othr>
    </Id>
  </DbtrAcct>
  <Cdtr>
    <Nm>Receiver Name</Nm>
  </Cdtr>
  <CdtrAcct>
    <Id>
      <Othr>
        <Id>987654321</Id>
      </Othr>
    </Id>
  </CdtrAcct>
</CdtTrfTxInf>
```

The transaction model can look like this:

```json theme={null}
{
  "id": "txn_01JVY8Y4N9X2M6S5Q7T1",
  "messageId": "20260407-000123",
  "source": {
    "type": "external_submission",
    "externalSubmission": {
      "id": "sub_01JVY8Y4N9X2M6S5Q7T1",
      "displayName": "Customer message submission"
    }
  },
  "type": "transfer",
  "status": "PENDING",
  "statusReason": null,
  "externalId": "TX-12345",
  "relatedTransactionId": null,
  "amounts": {
    "debit": {
      "amount": "1250.00",
      "currency": "USD"
    },
    "credit": {
      "amount": "1250.00",
      "currency": "USD"
    },
    "fees": [],
    "exchangeRate": "1.0000"
  },
  "debitInstrument": {
    "type": "ORIGINATOR",
    "originator": {
      "displayName": "Sender Name",
      "accountNumber": "123456789"
    }
  },
  "creditInstrument": {
    "type": "BENEFICIARY_ACCOUNT",
    "beneficiaryAccount": {
      "id": "987654321",
      "displayName": "Receiver Name",
      "currency": "USD"
    }
  }
}
```

## Related pages

* [Overview](/products/payout-origination/overview)
* [Base64 payload encoding](/products/payout-origination/base64-payload-encoding)
* [Authentication](/products/payout-origination/authentication)