139 lines
3.3 KiB
Markdown
139 lines
3.3 KiB
Markdown
# 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` |
|
|
|