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:

<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:

{
  "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:

<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:

{
  "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:

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`

3.3 KiB Raw Permalink Blame History