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.
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.
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.
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.
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.
Gateway Message can be fetched using the "Get message" endpoint (1). Once selected, we can click Send button (2) and check the response (3).
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.
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).
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.
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.
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:
Postman
Terminal
Step-by-step guide to use Terminal for Impel's ISO 20022 API
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.
Save the value of the messageId field in the received response, we will use it later in further requests as ${MESAGE_ID} variable.
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.
If the fullySigned flag is true, we can check if the same Gateway Message exists on Party B side.
Gateway Message on both sides should be the same, the only differences are related to message creation which is a normal behavior.
If the fullySigned flag is true, we can check if the proof exists and it is the same on Party B side.
Proof on both sides should be the same, the only differences are related to Proof creation and status update which is a normal behaviour.
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:
Name | Description |
---|---|
This documentation walks through exchanging an ISO 20022 financial message on Impel's platform using commands to call its REST API. This is the same walk through as described in article, but using terminal.
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 message type.
The message has to be wrapped in a.
The Gateway Message model is fully described .
Once a Gateway Message is processed by the system and acknowledged by the counterparty, the 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 and search for events related to proof creation.
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 .
Bank A Keycloak
https://auth-banka-sandbox.impel-lab577.co.uk/auth/realms/BBBBCAXXXXX client_id: gateway-api client_secret: UZbFa0uCD5NfaT9q
Bank B Keycloak
https://auth-bankb-sandbox.impel-lab577.co.uk/auth/realms/CCCCESXXXXX client_id: gateway-api client_secret: NiWaHZf8UmNYswWd
Bank A API
https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/api Authentication: OAuth2
Bank A API Swagger
Bank B API
https://api-sandbox.impel-lab577.co.uk/CCCCESXXXXX/api Authentication: OAuth2
Bank B API Swagger
Impel ISO 20022 platform has a distributed architecture, meaning that each platform participant has to have its own gateway service (node) in a platform with dedicated identity provider (Keycloak).
New platform participant has to complete onboarding process:
Request for a dedicated node in a platform.
Generate API credentials (clientId/clientSecret).
Gateway service (node) exposes API which can be used to send messages and get information about them. It uses dedicated Identity Provider (Keycloak) to authenticate and authorize API requests. Gateway service requires JWT token on every requests, which can be obtained from Keycloak, from OpenID Connect token endpoint. In order to get JWT access token we need to first generate clientId/clientSecret.
With Initial Access Token we need to create Keycloak client by running below command:
Response example:
Extract client_id and client_secret fields. From now we can use these credentials to get OAuth2 JWT token from Identity Provider (Keycloak).
When you create a client through the Client Registration Service the response will include a registration access token. The registration access token (registration_access_token) provides access to retrieve the client configuration later, but also to update or delete the client. The registration access token is included with the request in the same way as a bearer token or initial access token. Registration access tokens are only valid once, when it’s used the response will include a new token.
To secure whole process, we use feature. That means that platform participants will generate API client credentials.
When new dedicated Gateway service is setup in a network, an email will be sent with .