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.

Bank A

Request

curl --location --request POST \
'https://auth-banka-sandbox.impel-lab577.co.uk/auth/realms/BBBBCAXXXXX/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=gateway-api' \
--data-urlencode 'client_secret=UZbFa0uCD5NfaT9q' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=email'

Response example

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSQjI1NU5aVDRZM1kwTm9wdDFuSWphalZ5Nng3SW1HSDJGU2k2eEhRZlRFIn0.eyJleHAiOjE2NjM2Nzg0OTYsImlhdCI6MTY2MzY3ODE5NiwianRpIjoiN2ZjMDBiZWEtYjBmZS00OThlLTlmODQtZWQ4NDg4MWFlOGIyIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLWJhbmthLXVhdC5pbXBlbC1sYWI1NzcuY28udWsvYXV0aC9yZWFsbXMvQkJCQkNBWFhYWFgiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiNDY2OTJmNjItODkzZC00NDI1LTg1ZTItYWVlYjIwY2VhNTQyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiZ2F0ZXdheS1hcGkiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtYmJiYmNheHh4eHgiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiY2xpZW50SG9zdCI6Ijg3LjIwNi4xNTguMyIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiJnYXRld2F5LWFwaSIsInByZWZlcnJlZF91c2VybmFtZSI6IkJhbmsgQSIsImNsaWVudEFkZHJlc3MiOiI4Ny4yMDYuMTU4LjMifQ.MgtyibvvyGKOyvK4mb8RSvfoFi1jemziRm3Y6_mFks0tjOVfcuziBfvU5zkPBBH_OnKK2QBlc27ednI_cpYrqBqfuB2EtSxewAmIkFu7deuEqJFoFvixhy30NA7EFMTFUMFY04ycwpP6WjOOKZRYpyMr3J8lG5ANe0OTi6oeXr5lxuJFzsW2knDZDWmU2qnvAIYcIXFIamCXx5Wr344JiQFFj0LiskCXzE_Vd_zHdGUuUlcx7XvO92Ga4ovpXgf5Vi3Ely9syuzW3C2s83Ccg1Fz4UTBM_ws9pwXCz-Cp6Ereeulk8HdhDWsR_VeJrRaz49xMic5whHPub0T2H2gTQ",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

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.

Bank B

Request

curl --location --request POST \
'https://auth-bankb-sandbox.impel-lab577.co.uk/auth/realms/CCCCESXXXXX/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=gateway-api' \
--data-urlencode 'client_secret=NiWaHZf8UmNYswWd' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=email'

Response example

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSQjI1NU5aVDRZM1kwTm9wdDFuSWphalZ5Nng3SW1HSDJGU2k2eEhRZlRFIn0.eyJleHAiOjE2NjM2Nzg0OTYsImlhdCI6MTY2MzY3ODE5NiwianRpIjoiN2ZjMDBiZWEtYjBmZS00OThlLTlmODQtZWQ4NDg4MWFlOGIyIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLWJhbmthLXVhdC5pbXBlbC1sYWI1NzcuY28udWsvYXV0aC9yZWFsbXMvQkJCQkNBWFhYWFgiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiNDY2OTJmNjItODkzZC00NDI1LTg1ZTItYWVlYjIwY2VhNTQyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiZ2F0ZXdheS1hcGkiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtYmJiYmNheHh4eHgiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiY2xpZW50SG9zdCI6Ijg3LjIwNi4xNTguMyIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiJnYXRld2F5LWFwaSIsInByZWZlcnJlZF91c2VybmFtZSI6IkJhbmsgQSIsImNsaWVudEFkZHJlc3MiOiI4Ny4yMDYuMTU4LjMifQ.MgtyibvvyGKOyvK4mb8RSvfoFi1jemziRm3Y6_mFks0tjOVfcuziBfvU5zkPBBH_OnKK2QBlc27ednI_cpYrqBqfuB2EtSxewAmIkFu7deuEqJFoFvixhy30NA7EFMTFUMFY04ycwpP6WjOOKZRYpyMr3J8lG5ANe0OTi6oeXr5lxuJFzsW2knDZDWmU2qnvAIYcIXFIamCXx5Wr344JiQFFj0LiskCXzE_Vd_zHdGUuUlcx7XvO92Ga4ovpXgf5Vi3Ely9syuzW3C2s83Ccg1Fz4UTBM_ws9pwXCz-Cp6Ereeulk8HdhDWsR_VeJrRaz49xMic5whHPub0T2H2gTQ",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

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.

Request

curl --location --request POST \
'https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/api/gateway/iso20022/messages' \
--header 'Content-Type: application/xml' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_A_AUTH_TOKEN}' \
--data-raw '{
  "sender": "CCCCESXXXXX",
  "recipient": "BBBBCAXXXXX",
  "payloadType": "ISO20022",
  "payload": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?> <RequestPayload> <AppHdr xmlns=\"urn:iso:std:iso:20022:tech:xsd:head.001.001.02\"> <Fr> <FIId> <FinInstnId> <BICFI>BBBBCAXXXXX<\/BICFI> <\/FinInstnId> <\/FIId> <\/Fr> <To> <FIId> <FinInstnId> <BICFI>CCCCESXXXXX<\/BICFI> <\/FinInstnId> <\/FIId> <\/To> <BizMsgIdr>e3c3f21badaa-4869-b3ab-87674f71a358<\/BizMsgIdr> <MsgDefIdr>pacs.009.001.09<\/MsgDefIdr> <CreDt>2022-06-22T21:53:17.86282Z<\/CreDt> <\/AppHdr> <Document xmlns=\"urn:iso:std:iso:20022:tech:xsd:pacs.009.001.10\"> <FICdtTrf> <GrpHdr> <MsgId>e3c3f21badaa-4869-b3ab-87674f71a358<\/MsgId> <CreDtTm>2022-06-22T21:53:17.86282Z<\/CreDtTm> <NbOfTxs>1<\/NbOfTxs> <TtlIntrBkSttlmAmt Ccy=\"USD\">0.05<\/TtlIntrBkSttlmAmt> <IntrBkSttlmDt>2022-06-22Z<\/IntrBkSttlmDt> <SttlmInf> <SttlmMtd>INDA<\/SttlmMtd> <SttlmAcct> <Id> <IBAN>SE4321449568761374414331<\/IBAN> <\/Id> <\/SttlmAcct> <InstdRmbrsmntAgtAcct> <Id> <IBAN>SE4321449568761374414334<\/IBAN> <\/Id> <\/InstdRmbrsmntAgtAcct> <\/SttlmInf> <\/GrpHdr> <CdtTrfTxInf> <PmtId> <EndToEndId>e3c3f21badaa-4869-b3ab-87674f71a358<\/EndToEndId> <ClrSysRef>adam API test<\/ClrSysRef> <\/PmtId> <IntrBkSttlmAmt Ccy=\"USD\">0.05<\/IntrBkSttlmAmt> <IntrBkSttlmDt>2022-06-22Z<\/IntrBkSttlmDt> <SttlmPrty>NORM<\/SttlmPrty> <SttlmTmIndctn> <CdtDtTm>2022-06-22T21:57:47.86282Z<\/CdtDtTm> <\/SttlmTmIndctn> <Dbtr> <FinInstnId> <BICFI>BBBBCAXXXXX<\/BICFI> <\/FinInstnId> <\/Dbtr> <Cdtr> <FinInstnId> <BICFI>CCCCESXXXXX<\/BICFI> <\/FinInstnId> <\/Cdtr> <\/CdtTrfTxInf> <\/FICdtTrf> <\/Document> <\/RequestPayload>",
  "endToEndId": "9d33f3ab-816a-482d-8b25-8b5c9f3dbe36",
  "validate": true,
  "collateral": {
      "type": "NATIVE",
      "amount": 0.56,
      "exchangePrice": 1.2,
      "exchangeCurrency": "EUR"
  }
}'

Response example

{
   "messageId":"88fe1eff-e982-4cda-97cb-f229297d0dea"
}

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.

Request

curl --location --request GET \
'https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/api/gateway/iso20022/messages/${MESAGE_ID}/payload' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_A_AUTH_TOKEN}'

Response example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <RequestPayload> <AppHdr xmlns="urn:iso:std:iso:20022:tech:xsd:head.001.001.02"> <Fr> <FIId> <FinInstnId> <BICFI>BBBBCAXXXXX</BICFI> </FinInstnId> </FIId> </Fr> <To> <FIId> <FinInstnId> <BICFI>CCCCESXXXXX</BICFI> </FinInstnId> </FIId> </To> <BizMsgIdr>e3c3f21badaa-4869-b3ab-87674f71a358</BizMsgIdr> <MsgDefIdr>pacs.009.001.09</MsgDefIdr> <CreDt>2022-06-22T21:53:17.86282Z</CreDt> </AppHdr> <Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.009.001.10"> <FICdtTrf> <GrpHdr> <MsgId>e3c3f21badaa-4869-b3ab-87674f71a358</MsgId> <CreDtTm>2022-06-22T21:53:17.86282Z</CreDtTm> <NbOfTxs>1</NbOfTxs> <TtlIntrBkSttlmAmt Ccy="USD">0.05</TtlIntrBkSttlmAmt> <IntrBkSttlmDt>2022-06-22Z</IntrBkSttlmDt> <SttlmInf> <SttlmMtd>INDA</SttlmMtd> <SttlmAcct> <Id> <IBAN>SE4321449568761374414331</IBAN> </Id> </SttlmAcct> <InstdRmbrsmntAgtAcct> <Id> <IBAN>SE4321449568761374414334</IBAN> </Id> </InstdRmbrsmntAgtAcct> </SttlmInf> </GrpHdr> <CdtTrfTxInf> <PmtId> <EndToEndId>e3c3f21badaa-4869-b3ab-87674f71a358</EndToEndId> <ClrSysRef>adam API test</ClrSysRef> </PmtId> <IntrBkSttlmAmt Ccy="USD">0.05</IntrBkSttlmAmt> <IntrBkSttlmDt>2022-06-22Z</IntrBkSttlmDt> <SttlmPrty>NORM</SttlmPrty> <SttlmTmIndctn> <CdtDtTm>2022-06-22T21:57:47.86282Z</CdtDtTm> </SttlmTmIndctn> <Dbtr> <FinInstnId> <BICFI>BBBBCAXXXXX</BICFI> </FinInstnId> </Dbtr> <Cdtr> <FinInstnId> <BICFI>CCCCESXXXXX</BICFI> </FinInstnId> </Cdtr> </CdtTrfTxInf> </FICdtTrf> </Document> </RequestPayload>

Get message

The Gateway Message model is fully described here.

Request

curl --location --request GET \
'https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/api/gateway/iso20022/messages/${MESAGE_ID}' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_A_AUTH_TOKEN}'

Response example

{
    "id": "39a141ca-942f-41b2-b337-37b98391974c",
    "endToEndId": "b95ff4bb-a05f-429f-ad50-dc5f9cb07ab4",
    "sender": "CCCCESXXXXX",
    "recipient": "BBBBCAXXXXX",
    "payloadType": "ISO20022",
    "payload": null,
    "collateral": {
        "type": "NATIVE",
        "amount": 0.5600000000000000000000000,
        "exchangePrice": 1.2000000000000000000000000,
        "exchangeCurrency": "EUR",
        "tokenSymbol": null
    },
    "status": "ACKNOWLEDGED",
    "direction": "INBOX",
    "messageHash": "fJ+hNtRBP6YXNjfog7aZjTLh1nX4jN3/ncvPMxgg9Lhd9uDidhNZ0wqCdQWOKZ/MA4FTRUX1XPQ+QZg/XUyUVprl0kf2GrBWLQxRa+DQ6AlPou+vY0RXDYediNN8qy8g",
    "previousMessageHash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
    "fullySigned": true,
    "signature": "GTbaUds2amQxN9FWyT2QMTekriNM5wmSc2d5JjPxsVRPI/xyN/dAf0A9ToUb5dQcwejh0vEmK9/D5tiWQRJaj0F+BFp6TFBCpiT3PJOKUzu8lgN6uFk/GvU8PKE6xRQYnpC+tRkl4kWTok3OPFZpQgr+q7D7XBd7oJeLRDFtp3xxM/nKb/K0YXBPcOcFCTanzzK6bTvuNfQmg7q5g4IVLRW9WwYs15bAE/uwUoTINcs312Yi7UsFMdTfokHaDC5lvSdnN/efFcL8d8LiiiNUFjSxHEFqNCFMG2W2zqVkF0EKFJpfTeucjN7lNmp54K7CcWp74ASatZNVPoG7RPlYbg==",
    "counterSignature": "jXMRnV0Kq0jqqI4PghocygSJOGarcgV4ZwEiQWfDS+b80bncVJwLUeijmfdWTTeRm7G0Y4hNZGpIpNOcAJ93jx4gk7pCDwNy8mpHkWWV9fvPKzYuIxY+QBExYRFQCzsKdnD5VXetaTHP+7KOOLMFnAlQHFyCiQMDOZo9Y8gYbFCfndFTikpoN8Drs8kqje4Q3cvckp8wk6pOOnTg2KqP5nddO7TJrlERVXmf875TnccpgOhERd8Jy0LrZYVJuIUPxdstsYURRxtRlmT2KSdwZ0TxjCi6AmMAZjBaBCi/oM16AZC/cgoqlgV+9d4txa2SN+4OqcoZME/7o5vKw7T/Wg==",
    "proof": {
        "status": "APPROVED",
        "statusDate": "2022-10-14T18:39:35.806296Z",
        "channelHash": "624ed937a43630e775d9887b3386a41ea1bc9161072a271221bb3d8733bc86b3",
        "senderBic": "CCCCESXXXXX",
        "recipientBic": "BBBBCAXXXXX",
        "netSettlementCollaterals": [
            {
                "type": "NATIVE",
                "amount": 0.5600000000000000000000000,
                "tokenSymbol": null
            }
        ],
        "fullySigned": true,
        "signature": "f6OE/CwO539U95UwFgwLZh6t5ex7i/Y4sht1vzeDJhpDCC8Z89xqAI/RPsUbp3umblmwofFbDZDa0S6XhhQSKiaJvVFqoD87j7trAYAoPTGc0pucsoj0mVluIpBxx9F/pD95DA7mKQNxlWFOj2LgS5Gvnpo+ph8c1r3TUOZr1gxAWG4AdNczWhZuD55u4YCw7tB1jPg6sk5mHo6jcz/vZcyyEp8+nfSm+fhI8EzbAcS7qmF5Ju/1iYuxoc3dLZbdcUKKloX+FalRavCJK4rdeAWzGksdudRbxABo3Y4ERyDxMyNmU1rsq3ed9RcqBB44P+JI3Dczr0sQ8ZXGJfmzqQ==",
        "counterSignature": "izfZetOqzhGncksdSRk8TMcgbgPxhVLIdXPcaSFqF//rVSjO2x6956iICRC4rmxSZy7OFn15bT4Q/PrZBp62SjkdZG5UIflMIk1Ugrfm77+tcYboq2/9FtnMMgHxo9uLdw7oYbqL1470+NCaibGZIIXQ4zR10phWAEOl/ZMXTVmgzg5ISxClM+MlFthPOBFVcQIcgFrb5m+MfKwdTGqoQAhTfcsbfwTGW01ZjhuFNgkXo/iqOyjIcDabjgAmOpIC0iziq4tKUV51KHjoga5ab7p168NY92RC6nSYqPPpqK5GTP4ELGINkZrEyvxgQzs0uTnVtEJiNKPfBEfIMsUuiQ==",
        "messagesIds": [
            "39a141ca-942f-41b2-b337-37b98391974c"
        ],
        "endToEndIds": [
            "b95ff4bb-a05f-429f-ad50-dc5f9cb07ab4"
        ],
        "created": "2022-10-14T18:39:25.387876Z",
        "updated": "2022-10-14T18:39:28.667978Z"
    },
    "created": "2022-10-14T18:39:19.271786Z",
    "updated": "2022-10-14T18:39:25.394623Z"
}

Verification by Party B

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.

Request

curl --location --request GET \
'https://api-sandbox.impel-lab577.co.uk/CCCCESXXXXX/api/gateway/iso20022/messages/${MESAGE_ID}' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_B_AUTH_TOKEN}'

Response example

{
    "id": "39a141ca-942f-41b2-b337-37b98391974c",
    "endToEndId": "b95ff4bb-a05f-429f-ad50-dc5f9cb07ab4",
    "sender": "CCCCESXXXXX",
    "recipient": "BBBBCAXXXXX",
    "payloadType": "ISO20022",
    "payload": null,
    "collateral": {
        "type": "NATIVE",
        "amount": 0.5600000000000000000000000,
        "exchangePrice": 1.2000000000000000000000000,
        "exchangeCurrency": "EUR",
        "tokenSymbol": null
    },
    "status": "ACKNOWLEDGED",
    "direction": "OUTBOX",
    "messageHash": "fJ+hNtRBP6YXNjfog7aZjTLh1nX4jN3/ncvPMxgg9Lhd9uDidhNZ0wqCdQWOKZ/MA4FTRUX1XPQ+QZg/XUyUVprl0kf2GrBWLQxRa+DQ6AlPou+vY0RXDYediNN8qy8g",
    "previousMessageHash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
    "fullySigned": true,
    "signature": "GTbaUds2amQxN9FWyT2QMTekriNM5wmSc2d5JjPxsVRPI/xyN/dAf0A9ToUb5dQcwejh0vEmK9/D5tiWQRJaj0F+BFp6TFBCpiT3PJOKUzu8lgN6uFk/GvU8PKE6xRQYnpC+tRkl4kWTok3OPFZpQgr+q7D7XBd7oJeLRDFtp3xxM/nKb/K0YXBPcOcFCTanzzK6bTvuNfQmg7q5g4IVLRW9WwYs15bAE/uwUoTINcs312Yi7UsFMdTfokHaDC5lvSdnN/efFcL8d8LiiiNUFjSxHEFqNCFMG2W2zqVkF0EKFJpfTeucjN7lNmp54K7CcWp74ASatZNVPoG7RPlYbg==",
    "counterSignature": "jXMRnV0Kq0jqqI4PghocygSJOGarcgV4ZwEiQWfDS+b80bncVJwLUeijmfdWTTeRm7G0Y4hNZGpIpNOcAJ93jx4gk7pCDwNy8mpHkWWV9fvPKzYuIxY+QBExYRFQCzsKdnD5VXetaTHP+7KOOLMFnAlQHFyCiQMDOZo9Y8gYbFCfndFTikpoN8Drs8kqje4Q3cvckp8wk6pOOnTg2KqP5nddO7TJrlERVXmf875TnccpgOhERd8Jy0LrZYVJuIUPxdstsYURRxtRlmT2KSdwZ0TxjCi6AmMAZjBaBCi/oM16AZC/cgoqlgV+9d4txa2SN+4OqcoZME/7o5vKw7T/Wg==",
    "proof": {
        "status": "APPROVED",
        "statusDate": "2022-10-14T18:39:41.83429Z",
        "channelHash": "624ed937a43630e775d9887b3386a41ea1bc9161072a271221bb3d8733bc86b3",
        "senderBic": "CCCCESXXXXX",
        "recipientBic": "BBBBCAXXXXX",
        "netSettlementCollaterals": [
            {
                "type": "NATIVE",
                "amount": 0.5600000000000000000000000,
                "tokenSymbol": null
            }
        ],
        "fullySigned": true,
        "signature": "f6OE/CwO539U95UwFgwLZh6t5ex7i/Y4sht1vzeDJhpDCC8Z89xqAI/RPsUbp3umblmwofFbDZDa0S6XhhQSKiaJvVFqoD87j7trAYAoPTGc0pucsoj0mVluIpBxx9F/pD95DA7mKQNxlWFOj2LgS5Gvnpo+ph8c1r3TUOZr1gxAWG4AdNczWhZuD55u4YCw7tB1jPg6sk5mHo6jcz/vZcyyEp8+nfSm+fhI8EzbAcS7qmF5Ju/1iYuxoc3dLZbdcUKKloX+FalRavCJK4rdeAWzGksdudRbxABo3Y4ERyDxMyNmU1rsq3ed9RcqBB44P+JI3Dczr0sQ8ZXGJfmzqQ==",
        "counterSignature": "izfZetOqzhGncksdSRk8TMcgbgPxhVLIdXPcaSFqF//rVSjO2x6956iICRC4rmxSZy7OFn15bT4Q/PrZBp62SjkdZG5UIflMIk1Ugrfm77+tcYboq2/9FtnMMgHxo9uLdw7oYbqL1470+NCaibGZIIXQ4zR10phWAEOl/ZMXTVmgzg5ISxClM+MlFthPOBFVcQIcgFrb5m+MfKwdTGqoQAhTfcsbfwTGW01ZjhuFNgkXo/iqOyjIcDabjgAmOpIC0iziq4tKUV51KHjoga5ab7p168NY92RC6nSYqPPpqK5GTP4ELGINkZrEyvxgQzs0uTnVtEJiNKPfBEfIMsUuiQ==",
        "messagesIds": [
            "39a141ca-942f-41b2-b337-37b98391974c"
        ],
        "endToEndIds": [
            "b95ff4bb-a05f-429f-ad50-dc5f9cb07ab4"
        ],
        "created": "2022-10-14T18:39:24.881519Z",
        "updated": "2022-10-14T18:39:41.835388Z"
    },
    "created": "2022-10-14T18:39:13.978342Z",
    "updated": "2022-10-14T18:39:24.89147Z"
}

Get message proof

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.

Request

curl --location --request GET \
'https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/api/gateway/iso20022/messages/${MESAGE_ID}/proof' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_A_AUTH_TOKEN}'

Response example

{
    "status": "APPROVED",
    "statusDate": "2022-10-14T18:39:35.806296Z",
    "channelHash": "624ed937a43630e775d9887b3386a41ea1bc9161072a271221bb3d8733bc86b3",
    "senderBic": "CCCCESXXXXX",
    "recipientBic": "BBBBCAXXXXX",
    "netSettlementCollaterals": [
        {
            "type": "NATIVE",
            "amount": 0.5600000000000000000000000,
            "tokenSymbol": null
        }
    ],
    "fullySigned": true,
    "signature": "f6OE/CwO539U95UwFgwLZh6t5ex7i/Y4sht1vzeDJhpDCC8Z89xqAI/RPsUbp3umblmwofFbDZDa0S6XhhQSKiaJvVFqoD87j7trAYAoPTGc0pucsoj0mVluIpBxx9F/pD95DA7mKQNxlWFOj2LgS5Gvnpo+ph8c1r3TUOZr1gxAWG4AdNczWhZuD55u4YCw7tB1jPg6sk5mHo6jcz/vZcyyEp8+nfSm+fhI8EzbAcS7qmF5Ju/1iYuxoc3dLZbdcUKKloX+FalRavCJK4rdeAWzGksdudRbxABo3Y4ERyDxMyNmU1rsq3ed9RcqBB44P+JI3Dczr0sQ8ZXGJfmzqQ==",
    "counterSignature": "izfZetOqzhGncksdSRk8TMcgbgPxhVLIdXPcaSFqF//rVSjO2x6956iICRC4rmxSZy7OFn15bT4Q/PrZBp62SjkdZG5UIflMIk1Ugrfm77+tcYboq2/9FtnMMgHxo9uLdw7oYbqL1470+NCaibGZIIXQ4zR10phWAEOl/ZMXTVmgzg5ISxClM+MlFthPOBFVcQIcgFrb5m+MfKwdTGqoQAhTfcsbfwTGW01ZjhuFNgkXo/iqOyjIcDabjgAmOpIC0iziq4tKUV51KHjoga5ab7p168NY92RC6nSYqPPpqK5GTP4ELGINkZrEyvxgQzs0uTnVtEJiNKPfBEfIMsUuiQ==",
    "messagesIds": [
        "39a141ca-942f-41b2-b337-37b98391974c"
    ],
    "endToEndIds": [
        "b95ff4bb-a05f-429f-ad50-dc5f9cb07ab4"
    ],
    "created": "2022-10-14T18:39:25.387876Z",
    "updated": "2022-10-14T18:39:28.667978Z"
}

Verification by Party B

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.

Request

curl --location --request GET \
'https://api-sandbox.impel-lab577.co.uk/CCCCESXXXXX/api/gateway/iso20022/messages/${MESAGE_ID}/proof' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_B_AUTH_TOKEN}'

Response example

{
    "status": "APPROVED",
    "statusDate": "2022-10-14T18:39:41.83429Z",
    "channelHash": "624ed937a43630e775d9887b3386a41ea1bc9161072a271221bb3d8733bc86b3",
    "senderBic": "CCCCESXXXXX",
    "recipientBic": "BBBBCAXXXXX",
    "netSettlementCollaterals": [
        {
            "type": "NATIVE",
            "amount": 0.5600000000000000000000000,
            "tokenSymbol": null
        }
    ],
    "fullySigned": true,
    "signature": "f6OE/CwO539U95UwFgwLZh6t5ex7i/Y4sht1vzeDJhpDCC8Z89xqAI/RPsUbp3umblmwofFbDZDa0S6XhhQSKiaJvVFqoD87j7trAYAoPTGc0pucsoj0mVluIpBxx9F/pD95DA7mKQNxlWFOj2LgS5Gvnpo+ph8c1r3TUOZr1gxAWG4AdNczWhZuD55u4YCw7tB1jPg6sk5mHo6jcz/vZcyyEp8+nfSm+fhI8EzbAcS7qmF5Ju/1iYuxoc3dLZbdcUKKloX+FalRavCJK4rdeAWzGksdudRbxABo3Y4ERyDxMyNmU1rsq3ed9RcqBB44P+JI3Dczr0sQ8ZXGJfmzqQ==",
    "counterSignature": "izfZetOqzhGncksdSRk8TMcgbgPxhVLIdXPcaSFqF//rVSjO2x6956iICRC4rmxSZy7OFn15bT4Q/PrZBp62SjkdZG5UIflMIk1Ugrfm77+tcYboq2/9FtnMMgHxo9uLdw7oYbqL1470+NCaibGZIIXQ4zR10phWAEOl/ZMXTVmgzg5ISxClM+MlFthPOBFVcQIcgFrb5m+MfKwdTGqoQAhTfcsbfwTGW01ZjhuFNgkXo/iqOyjIcDabjgAmOpIC0iziq4tKUV51KHjoga5ab7p168NY92RC6nSYqPPpqK5GTP4ELGINkZrEyvxgQzs0uTnVtEJiNKPfBEfIMsUuiQ==",
    "messagesIds": [
        "39a141ca-942f-41b2-b337-37b98391974c"
    ],
    "endToEndIds": [
        "b95ff4bb-a05f-429f-ad50-dc5f9cb07ab4"
    ],
    "created": "2022-10-14T18:39:24.881519Z",
    "updated": "2022-10-14T18:39:41.835388Z"
}

Get events

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:

Request

curl --location --request GET \
'https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/api/gateway/iso20022/gateway/event?startDateTime=2022-09-11T15:15:04.378Z&endDateTime=2022-09-24T15:15:04.378Z&pageNumber=0&pageSize=10' \
--header 'Accept: */*' \
--header 'Authorization: Bearer ${BANK_A_AUTH_TOKEN}'

Response example

{
    "content": [
        {
            "id": "413ffaa6-457b-4704-9180-fe3e7f54d46f",
            "type": "MESSAGE_CREATED",
            "timestamp": "2022-10-14T18:27:15.369414Z",
            "subjectId": "25648bc4-b30f-4f0a-958c-514ccdbfafa2",
            "subjectType": "MESSAGE",
            "data": "eyJ0cmFjZUlkIjoiMjU2NDhiYzQtYjMwZi00ZjBhLTk1OGMtNTE0Y2NkYmZhZmEyIiwiZW5kVG9FbmRJZCI6IjcyMzNkMTk1LTdjYzMtNGFmNS1iMWYxLTY4ZWU3YjM3NDU1NSIsInBheWxvYWQiOiI8P3htbCB2ZXJzaW9uPVwiMS4wXCIgZW5jb2Rpbmc9XCJVVEYtOFwiPz5cbjxEb2N1bWVudCB4bWxucz1cInVybjppc286c3RkOmlzbzoyMDAyMjp0ZWNoOnhzZDpwYWluLjAwMi4wMDEuMDNcIj5cbiAgICA8Q3N0bXJQbXRTdHNScHQ+XG4gICAgICAgIDxHcnBIZHI+XG4gICAgICAgICAgICA8TXNnSWQ+UERVLjAwMDAwMDAxMjY8L01zZ0lkPlxuICAgICAgICAgICAgPENyZUR0VG0+MjAxMy0wNC0wNVQxNDo0Nzo1Ny4wMzczNDcyKzAyOjAwPC9DcmVEdFRtPlxuICAgICAgICAgICAgPEluaXRnUHR5PlxuICAgICAgICAgICAgICAgIDxJZD5cbiAgICAgICAgICAgICAgICAgICAgPE9yZ0lkPlxuICAgICAgICAgICAgICAgICAgICAgICAgPEJJQ09yQkVJPkJCQkJDQVhYWFhYPC9CSUNPckJFST5cbiAgICAgICAgICAgICAgICAgICAgPC9PcmdJZD5cbiAgICAgICAgICAgICAgICA8L0lkPlxuICAgICAgICAgICAgPC9Jbml0Z1B0eT5cbiAgICAgICAgPC9HcnBIZHI+XG4gICAgICAgIDxPcmdubEdycEluZkFuZFN0cz5cbiAgICAgICAgICAgIDxPcmdubE1zZ0lkPjMwMDAzMTI3MTY8L09yZ25sTXNnSWQ+XG4gICAgICAgICAgICA8T3JnbmxNc2dObUlkPnBhaW4uMDAxLjAwMS4wMzwvT3JnbmxNc2dObUlkPlxuICAgICAgICAgICAgPEdycFN0cz5BQ1RDPC9HcnBTdHM+XG4gICAgICAgIDwvT3JnbmxHcnBJbmZBbmRTdHM+XG4gICAgPC9Dc3RtclBtdFN0c1JwdD5cbjwvRG9jdW1lbnQ+XG4iLCJwYXlsb2FkVHlwZSI6IklTTzIwMDIyIn0="
        }
    ],
    "number": 0,
    "size": 1,
    "totalElements": 22,
    "last": false,
    "totalPages": 22,
    "sort": [],
    "first": true,
    "numberOfElements": 1
}

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.

PreviousPostmanNextR3 Corda Bridge

Last updated