Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The key aspects and components of Impel's ISO 20022 API
Send and receive financial messages between clients and other gateways
Committing message proofs onto the XDC Network's blockchain
Allowing digital assets such as the XDC Coin or US+ stablecoin to be included in the message's payload for instant settlement, without the need for traditional nostro/vostro accounts, nor the Central Banking system
Message
Proof
Event
A gateway service processes messages and proofs. Upon lifecycle state change, a new event message is generated. Clients retrieve events from the gateway service endpoint which is polled periodically by a Client:
GET /api/gateway/iso20022/gateway/event
Event Types are defined in API definition
MESSAGE_CREATED
Description: Triggered by a sender node when message is successfully created.
MESSAGE_SENT
Description: Triggered by a sender node when message is sent to a counterparty node.
MESSAGE_RECEIVED
Description: Triggered by a recipient node when a message is received and successfully created on a counterparty node.
MESSAGE_ACKNOWLEDGED
Description: Triggered by both (sender/recipient) nodes when a message is acknowledged by a counterparty node.
MESSAGE_NOT_ACKNOWLEDGED
Description: Triggered by both (sender/recipient) nodes when a message is not acknowledged by a counterparty node
PROOF_CREATED
Description: Triggered by a sender node when a proof is successfully created.
PROOF_SENT
Description: Triggered by a sender node when proof was sent to a counterparty.
PROOF_RECEIVED
Description: Triggered by a recipient node when a proof is received and successfully acknowledged by a counterparty node.
PROOF_ACKNOWLEDGED
Description: Triggered by both nodes when a proof is acknowledged by counterparty node.
PROOF_NOT_ACKNOWLEDGED
Description: Triggered by both nodes when a proof is not acknowledged by a counterparty node.
PROOF_COMMITTED
Description: Triggered by both nodes when a proof is successfully committed.
PROOF_APPROVED
Description: Triggered by both nodes when a proof is successfully approved.
PROOF_REJECTED
Description: Triggered by both nodes when a proof is rejected.
The message component of Impel's ISO 20022 API
The message component is the primary object to house the financial message's data and optional digital asset information used for collateral that is passed from one gateway node to another gateway node, essentially getting the ISO 20022 financial message from point a to point b.
Impel's ISO 20022 API gateway service's message envelope utilizes cryptography, ensuring the following:
High throughput
Instant delivery
Guaranteed delivery
Secured delivery
Impel's ISO 20022 API is an event driven system that contains defined events
An event represents a lifecycle state of a message and proof object. Learn more about event (computing) here on Wikipedia.
Description | |
---|---|
State | Description |
---|
id
Platform identifier
type
Type of an event e.g. (MESSAGE_CREATED, MESSAGE_SENT, etc.)
timestamp
Date/time event was created
subjectId
Identifier of a subject of the event
subjectType
Type of a subject of the event
data
Platform event serialized to JSON
NEW | Initial state of the message |
OUTBOX | Message is available to send to the counterparty |
SENT | Message has been sent to the counterparty |
RECEIVED | Message has been received by the counterparty |
ACKNOWLEDGED | Message has been checked and validated |
NOT_ACKNOWLEDGED | Message failed successful delivery |
The mechanics of Impel's ISO 20022 financial message
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.
The data required to route message between gateways (sender, receiver).
SendMessageRequest data field requirements:
Sender
Recipient
Payload
Collateral (optional)
Validation
head.001.001.01
head.001.001.02
head.001.001.03
AppHdr element:
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:
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:
XRC-20 token as collateral example:
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.
The AppHdr element is an ISO 20022 message. Supported schemes:
Variable | Description |
---|
${HEADER_TYPE} | head.001.001.01 and head.001.001.02 |
${SENDER_BIC} | Sending party's BIC |
${RECIPIENT_BIC} | Receiving party's BIC |
${BUSINESS_IDENTIFIER} | Identification |
${MESSAGE_TYPE} | pacs.009.001.10, pain.008.001.01, acmt.001.001.08, etc. |
${MESSAGE_DATE} | Date the message was created |
Detailed explanation of Impel's ISO 20022 API message confirmation
A Proof is a confirmation of a received message that has been validated, acknowledged (signed) by counter party, before it will be committed as a transaction on the XDC Network.
Messages received through the gateway service will be committed to the blockchain after successful proof validation via the following procedure:
Selects a batch of uncommitted messages
Creates a proof
Collects signatures
Commits proof
Approves/Rejects proof
Field | Description |
---|---|
An application programming interface is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how to build or use such a connection or interface is called an API specification. (as per )
The following API endpoints are located at this URL:
Field
Description
ID
Message identifier
endToEndId
Message business identifier (extracted from ISO 20022 Business Application Header)
Status
Status of message (CREATED, SENT. etc.)
Direction
Message direction (INBOX, OUTBOX)
Sender
Message sender Party BIC (extracted from ISO 20022 Business Application Header)
Recipient
Message recipient Party BIC (extracted from ISO 20022 Business Application Header)
Signature
Sender Party signature for a message to send (base64 format)
counterpartySignature
Recipient Party signature for a received message (base64 format)
messageHash
Hash of a message (base64 format)
previousMessageHash
Hash of a previous message in a chain (base64 format)
Collateral
Information about message collateral
Type
Type of collateral, e.g NATIVE (XDC) or ERC20
Amount
Collateral amount
exchangePrice
Price of a collateral amount
exchangeCurrency
Currency of a collateral amount price
tokenSymbol
XRC-20 token symbol (e.g. US+)
messageIds
List of proof's messages platform identifiers
endToEndIds
List of proof's messages business identifiers
status
Status of a proof in the platform (CREATED, SENT...)
sender
Proof sender Party BIC
recipient
Proof recipient Party BIC
signature
Sender Party signature for a proof to send
counterpartySignature
Recipient Party signature for a received proof
channelHash
Hash of a proof's messages (hex format)
netSettlementCollaterals
Sum of proof's messages collaterals
Message id
Created
Ok
Ok
OK
The bank identification code (i.e. SWIFT/BIC)
Ok
Unique identifier for this party
Name of party
Swift BIC for this party
URL for this party's gateway
Base64 encoded certificate
Addresses for this party
XinFin address
The RSQL filter to apply as search criteria
The zero-indexed page number, optional
The page size, optional with default being 10
Ok
A filter to get events from given date
A filter to get events to given date
The zero-indexed page number
The page size
Ok
The RSQL filter to apply as search criteria
The zero-indexed page number, optional
The page size, optional with default being 10
Ok
Unique identifier for this party
Name of party
Swift BIC for this party
URL for this party's gateway
Base64 encoded certificate
Addresses for this party
XinFin address
Send message request
Message end to end id
Sender BIC
Recipient BIC
Message payload type
Message payload
Collateral
Collateral type, e.g. native XDC or ERC20 token
Collateral amount
Collateral exchange price
Collateral exchange currency
ERC20 token symbol, required when type is equal to ERC20
Flag which enables payload validation
Accepted
Message id
Message id
Ok
Proof status
Proof status change date time
Proof channel hash as hex
Sender BIC
Recipient BIC
Net settlement collaterals
Collateral type, e.g. native XDC or ERC20 token
Collateral net settlement amount
ERC20 token symbol
Flag which tells if all parties signed a proof
Initiator signature
Counterparty signature
Proof's messages identifiers
Proof's messages identifiers
Proof's messages end to end identifiers
Proof's messages end to end identifiers
Proof creation date time
Proof update date time
Message id
Flag if payload should be returned in a response
Ok
Message id
Message end to end id
Sender BIC
Recipient BIC
Message payload type
Message payload - returned only if requested
Collateral
Collateral type, e.g. native XDC or ERC20 token
Collateral amount
Collateral exchange price
Collateral exchange currency
ERC20 token symbol, required when type is equal to ERC20
Message status
Message direction (INBOX|OUTBOX) which tells if message was sent or received
Message hash
Previous message hash
Flag which tells if all parties signed a message
Initiator signature
Counterparty signature
Proof
Proof status
Proof status change date time
Proof channel hash as hex
Sender BIC
Recipient BIC
Net settlement collaterals
Collateral type, e.g. native XDC or ERC20 token
Collateral net settlement amount
ERC20 token symbol
Flag which tells if all parties signed a proof
Initiator signature
Counterparty signature
Proof's messages identifiers
Proof's messages identifiers
Proof's messages end to end identifiers
Proof's messages end to end identifiers
Proof creation date time
Proof update date time
Message creation date time
Message update date time
The RSQL filter to apply as search criteria
The zero-indexed page number, optional
The page size, optional with default being 10
The field to use for sorting
The sort direction, either ASC or DESC
Ok
Message id
Message end to end id
Sender BIC
Recipient BIC
Message payload type
Message payload - returned only if requested
Collateral
Collateral type, e.g. native XDC or ERC20 token
Collateral amount
Collateral exchange price
Collateral exchange currency
ERC20 token symbol, required when type is equal to ERC20
Message status
Message direction (INBOX|OUTBOX) which tells if message was sent or received
Message hash
Previous message hash
Flag which tells if all parties signed a message
Initiator signature
Counterparty signature
Proof
Proof status
Proof status change date time
Proof channel hash as hex
Sender BIC
Recipient BIC
Net settlement collaterals
Collateral type, e.g. native XDC or ERC20 token
Collateral net settlement amount
ERC20 token symbol
Flag which tells if all parties signed a proof
Initiator signature
Counterparty signature
Proof's messages identifiers
Proof's messages identifiers
Proof's messages end to end identifiers
Proof's messages end to end identifiers
Proof creation date time
Proof update date time
Message creation date time
Message update date time