# ISO 20022 to DBIS Nostro/Vostro API Mapping

## Overview

This document provides mapping guidance for converting ISO 20022 messages to DBIS Nostro/Vostro API requests and vice versa.

## Message Types

### pacs.008 (Credit Transfer)

**ISO 20022 Structure**:
```xml
<Document>
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>MSG123</MsgId>
      <CreDtTm>2024-01-15T10:30:00Z</CreDtTm>
    </GrpHdr>
    <CdtTrfTxInf>
      <PmtId>
        <InstrId>INSTR123</InstrId>
        <EndToEndId>E2E123</EndToEndId>
      </PmtId>
      <IntrBkSttlmAmt Ccy="USD">1000.00</IntrBkSttlmAmt>
      <IntrBkSttlmDt>2024-01-15</IntrBkSttlmDt>
      <DbtrAcct>
        <Id>
          <IBAN>US64SVBKUS6S3300958879</IBAN>
        </Id>
      </DbtrAcct>
      <CdtrAcct>
        <Id>
          <IBAN>GB82WEST12345698765432</IBAN>
        </Id>
      </CdtrAcct>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>
```

**DBIS API Request**:
```json
{
  "fromAccountId": "US64SVBKUS6S3300958879",
  "toAccountId": "GB82WEST12345698765432",
  "amount": "1000.00",
  "currency": "USD",
  "valueDate": "2024-01-15",
  "reference": "E2E123",
  "metadata": {
    "iso20022MessageId": "MSG123",
    "instructionId": "INSTR123"
  }
}
```

### pacs.009 (Direct Debit)

Similar mapping to pacs.008, with reversed debit/credit roles.

### camt.053 (Bank Statement)

**ISO 20022 Structure**:
```xml
<Document>
  <BkToCstmrStmt>
    <Stmt>
      <Acct>
        <Id>
          <IBAN>US64SVBKUS6S3300958879</IBAN>
        </Id>
      </Acct>
      <Bal>
        <Tp>
          <CdOrPrtry>
            <Cd>CLBD</Cd>
          </CdOrPrtry>
        </Tp>
        <Amt Ccy="USD">1000000.00</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Dt>
          <Dt>2024-01-15</Dt>
        </Dt>
      </Bal>
    </Stmt>
  </BkToCstmrStmt>
</Document>
```

**DBIS API Response**:
```json
{
  "accountId": "ACC-123",
  "currentBalance": "1000000.00",
  "availableLiquidity": "950000.00",
  "holdAmount": "50000.00",
  "currency": "USD",
  "lastUpdatedAt": "2024-01-15T00:00:00Z"
}
```

## Field Mappings

| ISO 20022 Field | DBIS API Field | Notes |
|----------------|----------------|-------|
| `GrpHdr.MsgId` | `metadata.iso20022MessageId` | Message identifier |
| `PmtId.InstrId` | `metadata.instructionId` | Instruction ID |
| `PmtId.EndToEndId` | `reference` | End-to-end reference |
| `IntrBkSttlmAmt.value` | `amount` | Transfer amount |
| `IntrBkSttlmAmt.Ccy` | `currency` | Currency code |
| `IntrBkSttlmDt` | `valueDate` | Value date |
| `DbtrAcct.Id.IBAN` | `fromAccountId` | Debit account |
| `CdtrAcct.Id.IBAN` | `toAccountId` | Credit account |
| `DbtrAgt.FinInstnId.BICFI` | `fromParticipantId` | Debit institution |
| `CdtrAgt.FinInstnId.BICFI` | `toParticipantId` | Credit institution |

## Implementation

Use the `Iso20022Adapter` class:

```typescript
import { Iso20022Adapter } from '@/integration/plugins/iso20022-adapter';

const adapter = new Iso20022Adapter();
const message = await adapter.parseMessage(iso20022Xml);
const transferRequest = adapter.mapTransfer(message);
```

## Error Handling

ISO 20022 errors map to DBIS error codes:

| ISO 20022 Error | DBIS Error Code |
|----------------|-----------------|
| Invalid message format | `VALIDATION_ERROR` |
| Account not found | `NOT_FOUND` |
| Insufficient funds | `UNPROCESSABLE_ENTITY` |