Step-by-step guide to use Postman for Impel's ISO 20022 API
Impel's ISO 20022 platform provides a public Postman workspace, which allows users to call API endpoints in an easy and convenient way.
In this article we will walk through exchanging ISO 20022 message on Impel ISO 20022 platform using Postman.
The provided Postman collection has defined a script which will authenticate all requests, which means that there is no need to supply an access token.
Setup
Postman Public Workspace has to be forked in order to send requests. To do that we have to fork a collection and environments to our private workspace.
First we have to select Impel ISO 20022 collection (1) and then click on a Fork button (2).
Next we have to set a name of the new fork (1), select a Workspace, e.g. "My Workspace" which is a default one for every user (2) and click on Fork button (3).
When collection is forked next step is to fork environments. In order to do that we have to select Environments from left menu (1), next click on the more options on the right side of environment name (2) and select Create a Fork (3). We have to create a fork for both environments. On "Create a Fork" form we have to set a name and a workspace, the same as when we fork collection.
Once everything is done we can go to the workspace in which we created forks.
Environments
The Postman Workspace has two available Gateway Services named, respectively, Party A and Party B. Each Gateway Service is a separate node in Impel's ISO 20022 platform.
Send Message
First we need to select a Gateway Service, e.g. Party A (1).
Then choose Collections (2) from left menu and select Send message endpoint (3).
There are couple of examples for this endpoint, we will try with ISO 20022 message pain.002.001.03 (1).
We first have to copy the Body of the example and paste it in an endpoint request body (2). In the Body tab, we have to select the raw option (3) and then change its type to JSON (4). After that we can paste the example body into a request body window (5). Once that is done, we can click the Send button (6). In the response from the Gateway service we receive and messageId which is Impel ISO 20022 platform's identifier, which is set as global variable (gatewayMessageId) so later we can use GET endpoints without copying Gateway Message identifier - it will be set automatically.
Get Message payload
Sent Client Message request will be processed asynchronously by the platform and new Gateway Messages will be assigned Id as an identifier N.B. this can take a few seconds to create
Once Gateway Message is added in Impel ISO 20022 platform we can invoke "Get message" (1), with messageId (2) from the previous response. In order to do that we have to click the Send (3) button. A response will appear in the response window (4) with a body that is the same as the original Client Message.
Get Message
Gateway Message can be fetched using the "Get message" endpoint (1). Once selected, we can click Send button (2) and check the response (3).
Verification on Party B
If the fullySigned flag is true (1) then we know that message was already signed by Party B and we can verify that. In order to do that we just have to change environment to Party B (2) and click the Send button (3), and then in a response window (4) we should see the same data as on Party A side.
Gateway Messages on both sides should be the same, the only differences are related to Gateway Message creation which is normal behavior.
Get Message Proof
Once a Gateway Message is processed by the system and acknowledged by a counterparty, a Proof is created (it can take a few seconds to be created). We can wait few minutes after Gateway Message creation or try to get events using get events endpoint and search for an event related to the proof creation.
To get a proof we have to change the Gateway Service back to Party A (1). Then we have to choose "Get message proof" (2) and click the Send button (3). After that we will see a response with Proof data (4).
Verification on Party B
If the fullySigned flag is true (1), then we know that proof was already signed by Party B and we can verify this by changing the Gateway Service to Party B (2) and clicking the Send button (3). In the response window (4) we should see the same data as on Party A side.
Proof on both sides should be the same, the only differences are related to Proof creation and status update which is a normal behavior.
Get events
Every state change in Impel ISO 20022 platform is stored as an event, e.g. Gateway Message created, Gateway Message sent, Gateway Message received and many more.
Events can be fetched using endpoint "Get events" (1), setting the correct endDateTime request param (2), clicking the Send button (3) and waiting for a response (4).
The returned EventDto structure is a wrapper for a proper event triggered in the Impel ISO 20022 Gateway service. In order to get a real event, we have to deserialize the content of the data field. The data field stores an event as a series of bytes, and is a JSON string of serialized events. The type of event is given in the type field. Using the type and event schema from the API definition, we can deserialize the content of an event to a proper data model. A full list of events types and their data schema is available in Events article.
Terminal
Step-by-step guide to use Terminal for Impel's ISO 20022 API
This documentation walks through exchanging an ISO 20022 financial message on Impel's platform using curl commands to call its REST API.
This is the same walk through as described in Postman article, but using terminal.
Get the authentication token
The Impel ISO 20022 Gateway Service endpoints are secured, so in order to call them we have to get an authentication token from the Keycloak service.
We then save the value of the access_token field from the received response, which we will use in further requests as the ${BANK_A_AUTH_TOKEN} variable.
We will then save the value of the access_token field from the received response, which we will use it in further requests as the ${BANK_A_AUTH_TOKEN} variable.
The Authentication token is only valid for 5 minutes. After that time a new token has to be requested, otherwise endpoints will throw an "unauthorized" exception with HTTP status code 401.
Send message
Once we have a valid authentication token, we can exchange a Client Message with our counterparty using the Impel ISO 20022 platform. In the example below, we will use the ISO 20022 pacs.009.001.10 message type.
The pacs.009.001.10 message has to be wrapped in a Client Message.
Save the value of the messageId field in the received response, we will use it later in further requests as ${MESAGE_ID} variable.
Get message payload
Sent Client Message will be processed by the platform and new Gateway Message will be created with messageId as identifier. It can take a couple of seconds to create it.
Once the Gateway Message is added in a platform we can get it back from a platform.
Once a Gateway Message is processed by the system and acknowledged by the counterparty, the Proof is then created (though it can take a moment to be created). We can wait few minutes after Gateway Message creation or try to get events using get events endpoint and search for events related to proof creation.
Every state change in the Impel ISO 20022 platform is stored as an event, e.g. Gateway Message created, Gateway Message sent, Gateway Message received and many more. All events can be retrieved using the endpoint below:
The returned EventDto model is just a wrapper for a proper event triggered in Impel ISO 20022 node. In order to get a real event we have to deserialize the content of the data field. The data field stores events as a sequence of bytes, which is a JSON string of serialized events. The type of an event is given in a type property. Using the type and event schema from API definition we can deserialize the content of an event to proper data model. A full list of events types and their data schema is available in Events Article.
Sandbox - ISO 20022 API
Impel's sandbox environment to spin-up and test gateway nodes
Impel's ISO 20022 platform provides an experimental environment that can be used for demonstration and testing purposes, as well as to help understand how the platform works.
The Sandbox environment provides two default gateway services, a pretend Bank A and Bank B, allowing a user to exchange ISO 20022 messages between Gateway Clients.
There are two different ways to interact with Impel's ISO 20022 API, allowing for exchanging of financial messages between clients and gateway services: