Postman
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.
Last updated
