Message Request

The mechanics of Impel's ISO 20022 financial message

Overview

Impel's ISO 20022 API was designed to be message agnostic, meaning that it will house and send whatever data type the sender wants to send, MT or XML. The origination and fundamentals of the message that the client creates and sends to the gateway service that will be sent to the recipient that will be committed as a proof.

Schema

The data required to route message between gateways (sender, receiver).

SendMessageRequest data field requirements:

  • Sender

  • Recipient

  • Payload

  • Collateral (optional)

  • Validation

SendMessageRequest schema

SendMessageRequest:
      required:
        - endToEndId
        - payload
        - payloadType
        - recipient
        - sender
      type: object
      properties:
        endToEndId:
          type: string
          description: Message end to end id
          example: bec5d7a5-83e5-48e6-b6e8-3a1be45cba59
        sender:
          type: string
          description: Sender BIC
          example: BBBBCAXXXXX
        recipient:
          type: string
          description: Recipient BIC
          example: CCCCESXXXXX
        payloadType:
          type: string
          description: Message payload type
          example: ISO20022
          enum:
            - ISO20022
        payload:
          type: string
          description: Message payload
        collateral:
          $ref: '#/components/schemas/SendMessageRequestCollateral'
        validatePayload:
          type: boolean
          description: Flag which enables payload validation
          example: true
          default: false
    SendMessageRequestCollateral:
      required:
        - amount
        - type
      type: object
      properties:
        type:
          type: string
          description: Collateral type, e.g. native XDC or ERC20 token
          enum:
            - NATIVE
            - ERC20
        amount:
          type: number
          description: Collateral amount
        exchangePrice:
          type: number
          description: Collateral exchange price
        exchangeCurrency:
          type: string
          description: Collateral exchange currency
        tokenSymbol:
          type: string
          description: ERC20 token symbol, required when type is equal to ERC20
      description: Collateral

ISO 20022 Payload - AppHdr

The AppHdr element is an ISO 20022 head message. Supported schemes:

  • head.001.001.01

  • head.001.001.02

  • head.001.001.03

AppHdr element:

<AppHdr xmlns="urn:iso:std:iso:20022:tech:xsd:head.${HEADER_TYPE}">
        <Fr>
            <FIId>
                <FinInstnId>
                    <BICFI>${SENDER_BIC}</BICFI>
                </FinInstnId>
            </FIId>
        </Fr>
        <To>
            <FIId>
                <FinInstnId>
                    <BICFI>${RECIPIENT_BIC}</BICFI>
                </FinInstnId>
            </FIId>
        </To>
        <BizMsgIdr>${BUSINESS_IDENTIFIER}</BizMsgIdr>
        <MsgDefIdr>${MESSAGE_TYPE}</MsgDefIdr>
        <CreDt>${MESSAGE_DATE}</CreDt>
    </AppHdr>

ISO 20022 Payload - Document

The Document element is the actual ISO 20022 message e.g. PACS or PAIN.

The document schema attribute that points to the ISO 20022 schema type: urn:iso:std:iso:20022:tech:xsd:${MESSAGE_TYPE}

Example:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:${MESSAGE_TYPE}">
    ${ISO20022_MESSAGE_BODY}
</Document>

Collateral (digital asset)

The ability to add a digital asset to the message's payload allows for instant settlement capability to where traditional nostro/vostro accounts and settling up at the end of the day with the Central Banking systems is no longer required.

Collateral is defined in SendMessageRequest by the optional collateral field.

Digital assets types supported:

  • NATIVE (XDC, the native coin to the XDC Network)

  • XRC-20 token (layer 2 projects)

Native XDC coin as collateral example:

"collateral": {
  "type": "NATIVE",
  "amount": 0.56,
  "exchangePrice": 1.2,
  "exchangeCurrency": "EUR"
}

XRC-20 token as collateral example:

"collateral": {
  "type": "XRC20",
  "amount": 0.56,
  "exchangePrice": 1.2,
  "exchangeCurrency": "EUR",
  "tokenSymbol": "USDC"
}

Validation

All ISO 20022 message types and variants are candidates for validation. SendMessageRequest includes an optional flag "validatePayload" for validation.

ISO 20022 payload is validated by checking:

  • Document

  • AppHdr (optional)

Both elements has to be a valid ISO 20022 namespace, e.g.

  • urn:iso:std:iso:20022:tech:xsd:pain.002.001.03

  • urn:iso:std:iso:20022:tech:xsd:head.001.001.02

  • urn:iso:std:iso:20022:tech:xsd:pacs.002.001.12

Supplementary data is not supported by the platform.

Last updated