CurrenciCombo/docs/ISO_Message_Samples.md

# ISO-20022 Message Samples

## Overview
This document provides sample ISO-20022 message snippets (pacs.008, camt.052/053, camt.056) showing how plan metadata, digital signatures, and compliance attributes (LEI, DID, KYC, AML) are embedded in ISO messages for the Combo Flow system.

---

## 1. pacs.008 - Payment Instruction (with Plan ID and Signature)

### Complete Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.10"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <FIToFICstmrCdtTrf>
    <!-- Group Header -->
    <GrpHdr>
      <MsgId>MSG-2025-01-15-001234</MsgId>
      <CreDtTm>2025-01-15T10:30:00.000Z</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>78000.00</CtrlSum>
      <InitgPty>
        <Nm>Example Corp Ltd.</Nm>
        <Id>
          <OrgId>
            <Othr>
              <Id>5493000IBP32UQZ0KL24</Id>
              <SchmeNm>
                <Cd>LEI</Cd>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
        <CtctDtls>
          <Email>compliance@example.com</Email>
          <PhneNb>+49-30-12345678</PhneNb>
        </CtctDtls>
      </InitgPty>
    </GrpHdr>

    <!-- Credit Transfer Transaction Information -->
    <CdtTrfTxInf>
      <!-- Payment Identification -->
      <PmtId>
        <EndToEndId>PLAN-12345678-ABCD-EFGH-IJKL</EndToEndId>
        <TxId>TX-2025-01-15-001234</TxId>
        <UETR>550e8400-e29b-41d4-a716-446655440000</UETR>
      </PmtId>

      <!-- Payment Type Information -->
      <PmtTpInf>
        <SvcLvl>
          <Cd>SEPA</Cd>
        </SvcLvl>
        <LclInstrm>
          <Cd>INST</Cd>
        </LclInstrm>
        <CtgyPurp>
          <Cd>SUPP</Cd>
        </CtgyPurp>
      </PmtTpInf>

      <!-- Interbank Settlement Amount -->
      <IntrBkSttlmAmt Ccy="EUR">78000.00</IntrBkSttlmAmt>

      <!-- Instructing Agent -->
      <InstgAgt>
        <FinInstnId>
          <BICFI>BANKDEFFXXX</BICFI>
          <Nm>Example Bank AG</Nm>
        </FinInstnId>
      </InstgAgt>

      <!-- Instructed Agent -->
      <InstdAgt>
        <FinInstnId>
          <BICFI>BENEFRPPXXX</BICFI>
          <Nm>Beneficiary Bank</Nm>
        </FinInstnId>
      </InstdAgt>

      <!-- Debtor -->
      <Dbtr>
        <Nm>Example Corp Ltd.</Nm>
        <PstlAdr>
          <StrtNm>Main Street</StrtNm>
          <BldgNb>123</BldgNb>
          <PstCd>10115</PstCd>
          <TwnNm>Berlin</TwnNm>
          <Ctry>DE</Ctry>
        </PstlAdr>
        <Id>
          <OrgId>
            <Othr>
              <Id>5493000IBP32UQZ0KL24</Id>
              <SchmeNm>
                <Cd>LEI</Cd>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
        <CtctDtls>
          <Email>compliance@example.com</Email>
        </CtctDtls>
      </Dbtr>

      <!-- Debtor Account -->
      <DbtrAcct>
        <Id>
          <IBAN>DE89370400440532013000</IBAN>
        </Id>
        <Tp>
          <Cd>CACC</Cd>
        </Tp>
      </DbtrAcct>

      <!-- Debtor Agent -->
      <DbtrAgt>
        <FinInstnId>
          <BICFI>BANKDEFFXXX</BICFI>
        </FinInstnId>
      </DbtrAgt>

      <!-- Creditor -->
      <Cdtr>
        <Nm>Beneficiary Corp</Nm>
        <PstlAdr>
          <StrtNm>Beneficiary Street</StrtNm>
          <BldgNb>456</BldgNb>
          <PstCd>20095</PstCd>
          <TwnNm>Hamburg</TwnNm>
          <Ctry>DE</Ctry>
        </PstlAdr>
      </Cdtr>

      <!-- Creditor Account -->
      <CdtrAcct>
        <Id>
          <IBAN>DE89370400440532013001</IBAN>
        </Id>
        <Tp>
          <Cd>CACC</Cd>
        </Tp>
      </CdtrAcct>

      <!-- Creditor Agent -->
      <CdtrAgt>
        <FinInstnId>
          <BICFI>BENEFRPPXXX</BICFI>
        </FinInstnId>
      </CdtrAgt>

      <!-- Remittance Information -->
      <RmtInf>
        <Ustrd>Plan ID: PLAN-12345678-ABCD-EFGH-IJKL | Combo Flow Execution</Ustrd>
        <Strd>
          <RfrdDocInf>
            <Tp>
              <CdOrPrtry>
                <Cd>CINV</Cd>
              </CdOrPrtry>
            </Tp>
            <Nb>PLAN-12345678-ABCD-EFGH-IJKL</Nb>
            <RltdDt>2025-01-15</RltdDt>
          </RfrdDocInf>
          <RfrdDocAmt>
            <DuePyblAmt Ccy="EUR">78000.00</DuePyblAmt>
          </RfrdDocAmt>
          <RfrdDocRltdInf>
            <RfrdDocTp>
              <CdOrPrtry>
                <Cd>PUOR</Cd>
              </CdOrPrtry>
            </RfrdDocTp>
            <RfrdDocRef>DLT-TX-0x1234567890abcdef1234567890abcdef12345678</RfrdDocRef>
          </RfrdDocRltdInf>
        </Strd>
      </RmtInf>

      <!-- Supplementary Data (Compliance & Plan Metadata) -->
      <SplmtryData>
        <PlcAndNm>ComboFlowComplianceData</PlcAndNm>
        <Envlp>
          <ComboFlowData xmlns="urn:example:comboflow:xsd:1.0">
            <!-- Plan Identification -->
            <PlanId>PLAN-12345678-ABCD-EFGH-IJKL</PlanId>
            <PlanHash>0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890</PlanHash>
            <ExecutionId>EXEC-2025-01-15-001234</ExecutionId>

            <!-- Compliance Attributes -->
            <Compliance>
              <LEI>5493000IBP32UQZ0KL24</LEI>
              <DID>did:web:example.com:user:123</DID>
              <KYC>
                <Level>2</Level>
                <Provider>Onfido</Provider>
                <Verified>true</Verified>
                <VerifiedAt>2025-01-10T08:00:00Z</VerifiedAt>
                <ExpiresAt>2026-12-31T23:59:59Z</ExpiresAt>
              </KYC>
              <AML>
                <Passed>true</Passed>
                <Provider>Chainalysis</Provider>
                <LastCheck>2025-01-15T09:00:00Z</LastCheck>
                <RiskLevel>LOW</RiskLevel>
                <ScreeningReference>AML-REF-2025-01-15-001</ScreeningReference>
              </AML>
            </Compliance>

            <!-- Digital Signature -->
            <DigitalSignature>
              <Algorithm>ECDSA</Algorithm>
              <Curve>secp256k1</Curve>
              <HashAlgorithm>SHA-256</HashAlgorithm>
              <SignerAddress>0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb</SignerAddress>
              <SignatureValue>0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef</SignatureValue>
              <SignedAt>2025-01-15T10:25:00Z</SignedAt>
            </DigitalSignature>

            <!-- DLT Transaction Reference -->
            <DLTReference>
              <ChainId>1</ChainId>
              <Network>Ethereum Mainnet</Network>
              <TransactionHash>0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef</TransactionHash>
              <BlockNumber>18500000</BlockNumber>
              <BlockTimestamp>2025-01-15T10:29:45Z</BlockTimestamp>
            </DLTReference>

            <!-- Notary Proof -->
            <NotaryProof>
              <ProofHash>0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321</ProofHash>
              <NotaryAddress>0xNotaryRegistryContractAddress</NotaryAddress>
              <NotarizedAt>2025-01-15T10:28:00Z</NotarizedAt>
            </NotaryProof>

            <!-- Workflow Steps Summary -->
            <WorkflowSteps>
              <Step index="1" type="borrow" asset="CBDC_USD" amount="100000" />
              <Step index="2" type="swap" from="CBDC_USD" to="CBDC_EUR" amount="100000" />
              <Step index="3" type="repay" asset="CBDC_USD" amount="20000" />
              <Step index="4" type="pay" asset="EUR" amount="78000" />
            </WorkflowSteps>
          </ComboFlowData>
        </Envlp>
      </SplmtryData>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>
```

### Key Elements

1. **Plan ID in `EndToEndId`**: `PLAN-12345678-ABCD-EFGH-IJKL`
2. **LEI in `InitgPty.Id`** and **`Dbtr.Id`**: `5493000IBP32UQZ0KL24`
3. **DLT Reference in `RmtInf`**: DLT transaction hash
4. **Compliance Data in `SplmtryData`**: Full compliance attributes (LEI, DID, KYC, AML)
5. **Digital Signature in `SplmtryData`**: User's wallet signature
6. **Notary Proof in `SplmtryData`**: Notary registry proof hash

---

## 2. camt.052 - Bank Statement (for Reconciliation)

### Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.052.001.11">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>STMT-2025-01-15-001</MsgId>
      <CreDtTm>2025-01-15T11:00:00Z</CreDtTm>
      <MsgRcpt>
        <Nm>Example Corp Ltd.</Nm>
        <Id>
          <OrgId>
            <Othr>
              <Id>5493000IBP32UQZ0KL24</Id>
              <SchmeNm>
                <Cd>LEI</Cd>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
      </MsgRcpt>
    </GrpHdr>
    <Stmt>
      <Id>STMT-2025-01-15-001</Id>
      <CreDtTm>2025-01-15T11:00:00Z</CreDtTm>
      <Acct>
        <Id>
          <IBAN>DE89370400440532013000</IBAN>
        </Id>
        <Tp>
          <Cd>CACC</Cd>
        </Tp>
        <Ccy>EUR</Ccy>
      </Acct>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>OPBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">100000.00</Amt>
        <Dt>
          <Dt>2025-01-15</Dt>
        </Dt>
      </Bal>
      <Ntry>
        <Amt Ccy="EUR">-78000.00</Amt>
        <CdtDbtInd>DBIT</CdtDbtInd>
        <Sts>BOOK</Sts>
        <BookgDt>
          <Dt>2025-01-15</Dt>
        </BookgDt>
        <ValDt>
          <Dt>2025-01-15</Dt>
        </ValDt>
        <AcctSvcrRef>TX-2025-01-15-001234</AcctSvcrRef>
        <BkTxCd>
          <Domn>
            <Cd>PMNT</Cd>
            <Fmly>
              <Cd>ICDT</Cd>
              <SubFmlyCd>ESCT</SubFmlyCd>
            </Fmly>
          </Domn>
        </BkTxCd>
        <NtryDtls>
          <TxDtls>
            <Refs>
              <EndToEndId>PLAN-12345678-ABCD-EFGH-IJKL</EndToEndId>
              <TxId>TX-2025-01-15-001234</TxId>
            </Refs>
            <RmtInf>
              <Ustrd>Plan ID: PLAN-12345678-ABCD-EFGH-IJKL</Ustrd>
            </RmtInf>
            <RltdPties>
              <Cdtr>
                <Nm>Beneficiary Corp</Nm>
              </Cdtr>
            </RltdPties>
          </TxDtls>
        </NtryDtls>
      </Ntry>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>CLBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="EUR">22000.00</Amt>
        <Dt>
          <Dt>2025-01-15</Dt>
        </Dt>
      </Bal>
    </Stmt>
  </BkToCstmrStmt>
</Document>
```

### Key Elements

1. **Plan ID in `EndToEndId`**: Links statement entry to execution plan
2. **LEI in `MsgRcpt.Id`**: Account holder's LEI
3. **Transaction Reference**: Links to original payment instruction

---

## 3. camt.053 - Account Statement (Detailed)

### Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.10">
  <BkToCstmrStmt>
    <GrpHdr>
      <MsgId>STMT-DETAIL-2025-01-15-001</MsgId>
      <CreDtTm>2025-01-15T11:00:00Z</CreDtTm>
    </GrpHdr>
    <Stmt>
      <Id>STMT-DETAIL-2025-01-15-001</Id>
      <Acct>
        <Id>
          <IBAN>DE89370400440532013000</IBAN>
        </Id>
      </Acct>
      <Ntry>
        <Amt Ccy="EUR">-78000.00</Amt>
        <CdtDbtInd>DBIT</CdtDbtInd>
        <Sts>BOOK</Sts>
        <BookgDt>
          <Dt>2025-01-15</Dt>
        </BookgDt>
        <NtryDtls>
          <TxDtls>
            <Refs>
              <EndToEndId>PLAN-12345678-ABCD-EFGH-IJKL</EndToEndId>
              <AcctSvcrRef>TX-2025-01-15-001234</AcctSvcrRef>
            </Refs>
            <RmtInf>
              <Ustrd>Plan ID: PLAN-12345678-ABCD-EFGH-IJKL | DLT TX: 0x1234...5678</Ustrd>
            </RmtInf>
            <RltdPties>
              <Dbtr>
                <Nm>Example Corp Ltd.</Nm>
                <Id>
                  <OrgId>
                    <Othr>
                      <Id>5493000IBP32UQZ0KL24</Id>
                      <SchmeNm>
                        <Cd>LEI</Cd>
                      </SchmeNm>
                    </Othr>
                  </OrgId>
                </Id>
              </Dbtr>
              <Cdtr>
                <Nm>Beneficiary Corp</Nm>
              </Cdtr>
            </RltdPties>
            <RltdAgts>
              <DbtrAgt>
                <FinInstnId>
                  <BICFI>BANKDEFFXXX</BICFI>
                </FinInstnId>
              </DbtrAgt>
            </RltdAgts>
          </TxDtls>
        </NtryDtls>
      </Ntry>
    </Stmt>
  </BkToCstmrStmt>
</Document>
```

---

## 4. camt.056 - Cancellation Request (for Rollback)

### Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.056.001.10">
  <FIToFIPmtCxlReq>
    <GrpHdr>
      <MsgId>CANCEL-2025-01-15-001</MsgId>
      <CreDtTm>2025-01-15T10:35:00Z</CreDtTm>
      <InitgPty>
        <Nm>Example Corp Ltd.</Nm>
        <Id>
          <OrgId>
            <Othr>
              <Id>5493000IBP32UQZ0KL24</Id>
              <SchmeNm>
                <Cd>LEI</Cd>
              </SchmeNm>
            </Othr>
          </OrgId>
        </Id>
      </InitgPty>
    </GrpHdr>
    <Undrlyg>
      <TxInf>
        <CxlId>CANCEL-TX-2025-01-15-001</CxlId>
        <CxlRsn>
          <Cd>DUPL</Cd>
          <AddtlInf>DLT execution failed. Rolling back payment instruction.</AddtlInf>
        </CxlRsn>
        <OrgnlGrpInf>
          <OrgnlMsgId>MSG-2025-01-15-001234</OrgnlMsgId>
          <OrgnlMsgNmId>pacs.008.001.10</OrgnlMsgNmId>
          <OrgnlCreDtTm>2025-01-15T10:30:00Z</OrgnlCreDtTm>
        </OrgnlGrpInf>
        <OrgnlInstrId>TX-2025-01-15-001234</OrgnlInstrId>
        <OrgnlEndToEndId>PLAN-12345678-ABCD-EFGH-IJKL</OrgnlEndToEndId>
        <OrgnlInstdAmt>
          <Amt Ccy="EUR">78000.00</Amt>
        </OrgnlInstdAmt>
        <OrgnlTxRef>
          <EndToEndId>PLAN-12345678-ABCD-EFGH-IJKL</EndToEndId>
          <TxId>TX-2025-01-15-001234</TxId>
        </OrgnlTxRef>
        <SplmtryData>
          <PlcAndNm>ComboFlowRollbackData</PlcAndNm>
          <Envlp>
            <RollbackData xmlns="urn:example:comboflow:xsd:1.0">
              <PlanId>PLAN-12345678-ABCD-EFGH-IJKL</PlanId>
              <RollbackReason>DLT_EXECUTION_FAILED</RollbackReason>
              <DLTState>ROLLED_BACK</DLTState>
              <NotaryProof>0xfedcba0987654321...</NotaryProof>
            </RollbackData>
          </Envlp>
        </SplmtryData>
      </TxInf>
    </Undrlyg>
  </FIToFIPmtCxlReq>
</Document>
```

### Key Elements

1. **Cancellation Reason**: `DLT execution failed`
2. **Original Plan ID**: `PLAN-12345678-ABCD-EFGH-IJKL`
3. **Rollback Data**: DLT state and notary proof in supplementary data

---

## 5. Message Generation Code

### TypeScript Example

```typescript
import { generateISO20022Message } from '@comboflow/iso20022';

const generatePaymentInstruction = async (
  plan: Plan,
  compliance: ComplianceStatus,
  signature: string,
  dltTxHash: string,
  notaryProof: string
): Promise<string> => {
  const isoMessage = generateISO20022Message({
    messageType: 'pacs.008',
    groupHeader: {
      messageId: `MSG-${Date.now()}`,
      creationDateTime: new Date(),
      initiatingParty: {
        name: 'Example Corp Ltd.',
        lei: compliance.lei
      }
    },
    creditTransfer: {
      paymentId: {
        endToEndId: plan.planId,
        transactionId: `TX-${Date.now()}`
      },
      amount: {
        currency: 'EUR',
        value: 78000.00
      },
      debtor: {
        name: 'Example Corp Ltd.',
        lei: compliance.lei,
        account: {
          iban: 'DE89370400440532013000'
        }
      },
      creditor: {
        name: 'Beneficiary Corp',
        account: {
          iban: 'DE89370400440532013001'
        }
      },
      remittanceInformation: {
        unstructured: `Plan ID: ${plan.planId} | Combo Flow Execution`
      },
      supplementaryData: {
        planId: plan.planId,
        planHash: plan.planHash,
        compliance: {
          lei: compliance.lei,
          did: compliance.did,
          kyc: compliance.kyc,
          aml: compliance.aml
        },
        digitalSignature: {
          algorithm: 'ECDSA',
          signerAddress: plan.signerAddress,
          signatureValue: signature
        },
        dltReference: {
          chainId: 1,
          transactionHash: dltTxHash
        },
        notaryProof: {
          proofHash: notaryProof
        }
      }
    }
  });

  return isoMessage;
};
```

---

**Document Version**: 1.0  
**Last Updated**: 2025-01-15  
**Author**: Integration Team