API Specification

Complete list of the ISO 20022 API's endpoints (methods)

Overview

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 Wikipedia)

The following API endpoints are located at this URL: https://api-sandbox.impel-lab577.co.uk/BBBBCAXXXXX/swagger-ui/index.html?configUrl=/BBBBCAXXXXX/v3/api-docs/swagger-config

Impel's ISO 20022 API Endpoints (methods)

Get messages

GEThttp://localhost:8092/api/gateway/iso20022/messages

Query parameters

Response

200400500

Ok

Body

*/*

content*array of MessageInfo (object)

number*integer (int32)

size*integer (int32)

totalElements*integer (int64)

last*boolean

totalPages*integer (int32)

sortarray of OrderDto (object)

first*boolean

numberOfElements*integer (int32)

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/messages', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "content": [
    {
      "id": "fc53b37d-ebfc-4e99-99ca-001cb47d3819",
      "endToEndId": "e3c3f21badaa-4869-b3ab-87674f71a358",
      "sender": "BBBBCAXXXXX",
      "recipient": "CCCCESXXXXX",
      "payloadType": "ISO20022",
      "payload": "text",
      "collateral": {
        "type": "NATIVE",
        "amount": 0,
        "exchangePrice": 0,
        "exchangeCurrency": "text",
        "tokenSymbol": "text"
      },
      "status": "APPROVED",
      "direction": "OUTBOX",
      "messageHash": "text",
      "previousMessageHash": "text",
      "fullySigned": true,
      "signature": "text",
      "counterSignature": "text",
      "proof": {
        "status": "SENT",
        "statusDate": "2022-07-12T23:37:25.466566+02:00",
        "channelHash": "text",
        "senderBic": "BBBBCAXXXXX",
        "recipientBic": "CCCCESXXXXX",
        "netSettlementCollaterals": [
          {
            "type": "NATIVE",
            "amount": 0,
            "tokenSymbol": "text"
          }
        ],
        "fullySigned": true,
        "signature": "text",
        "counterSignature": "text",
        "messagesIds": [
          "123e4567-e89b-12d3-a456-426614174000"
        ],
        "endToEndIds": [
          "text"
        ],
        "created": "2022-07-12T23:37:25.466566+02:00",
        "updated": "2022-07-12T23:37:22.401717+02:00"
      },
      "created": "2022-07-12T23:37:25.466566+02:00",
      "updated": "2022-07-12T23:37:22.401717+02:00"
    }
  ],
  "last": false,
  "sort": [
    {
      "property": "text",
      "direction": "ASC"
    }
  ],
  "first": false
}

Send message

POSThttp://localhost:8092/api/gateway/iso20022/messages

Body

application/json

Send message request

endToEndId*string

Message end to end id

sender*string

Sender BIC

recipient*string

Recipient BIC

payloadType*enum

Message payload type

ISO20022

payload*string

Message payload

collateralSendMessageRequestCollateral (object)

Collateral

validateboolean

Flag which enables payload validation

Response

202400500

Accepted

Body

*/*

messageId*string (uuid)

Message id

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/messages', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "endToEndId": "bec5d7a5-83e5-48e6-b6e8-3a1be45cba59",
      "payload": "text",
      "payloadType": "ISO20022",
      "recipient": "CCCCESXXXXX",
      "sender": "BBBBCAXXXXX"
    }),
});
const data = await response.json();

Response

{
  "messageId": "b40a54d4-a748-4465-a6ea-bc5a91ad80e7"
}

Get events page from a dates range sorted by timestamp ascending

GEThttp://localhost:8092/api/gateway/iso20022/gateway/event

Query parameters

Response

200400500

Ok

Body

*/*

content*array of EventDto (object)

number*integer (int32)

size*integer (int32)

totalElements*integer (int64)

last*boolean

totalPages*integer (int32)

sortarray of OrderDto (object)

first*boolean

numberOfElements*integer (int32)

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/gateway/event', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "MESSAGE_CREATED",
      "timestamp": "2024-04-26T03:20:20.096Z",
      "subjectId": "text",
      "subjectType": "MESSAGE",
      "data": "Ynl0ZXM="
    }
  ],
  "last": false,
  "sort": [
    {
      "property": "text",
      "direction": "ASC"
    }
  ],
  "first": false
}

Endpoint providing information about produced cloud events data models

OPTIONShttp://localhost:8092/api/gateway/iso20022/gateway/event

Response

200400500

OK

Body

*/*

one of

MessageCreatedEvent (object)MessageReceivedEvent (object)MessageSentEvent (object)MessageAcknowledgedEvent (object)MessageNotAcknowledgedEvent (object)ProofAcknowledgedEvent (object)ProofApprovedEvent (object)ProofCommittedEvent (object)ProofCreatedEvent (object)ProofNotAcknowledgedEvent (object)ProofReceivedEvent (object)ProofRejectedEvent (object)ProofSentEvent (object)

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/gateway/event', {
    method: 'OPTIONS',
    headers: {},
});
const data = await response.json();

Response

{
  "traceId": "123e4567-e89b-12d3-a456-426614174000",
  "endToEndId": "text",
  "payload": "text",
  "payloadType": "ISO20022"
}

Get message

GEThttp://localhost:8092/api/gateway/iso20022/messages/{messageId}

Path parameters

messageId*string (uuid)

Message id

Query parameters

Response

200400404500

Ok

Body

*/*

id*string (uuid)

Message id

endToEndId*string

Message end to end id

sender*string

Sender BIC

recipient*string

Recipient BIC

payloadType*enum

Message payload type

ISO20022

payloadstring

Message payload - returned only if requested

collateralMessageInfoCollateral (object)

Collateral

status*enum

Message status

NEWOUTBOXSENTACKNOWLEDGEDNOT_ACKNOWLEDGEDRECEIVED

direction*enum

Message direction (INBOX|OUTBOX) which tells if message was sent or received

INBOXOUTBOX

messageHashstring (base64)

Message hash

previousMessageHashstring (base64)

Previous message hash

fullySigned*boolean

Flag which tells if all parties signed a message

signaturestring (base64)

Initiator signature

counterSignaturestring (base64)

Counterparty signature

proofProofInfo (object)

Proof

createdstring (date-time)

Message creation date time

updatedstring (date-time)

Message update date time

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/messages/{messageId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "fc53b37d-ebfc-4e99-99ca-001cb47d3819",
  "endToEndId": "e3c3f21badaa-4869-b3ab-87674f71a358",
  "sender": "BBBBCAXXXXX",
  "recipient": "CCCCESXXXXX",
  "payloadType": "ISO20022",
  "payload": "text",
  "collateral": {
    "type": "NATIVE",
    "amount": 0,
    "exchangePrice": 0,
    "exchangeCurrency": "text",
    "tokenSymbol": "text"
  },
  "status": "APPROVED",
  "direction": "OUTBOX",
  "messageHash": "text",
  "previousMessageHash": "text",
  "fullySigned": true,
  "signature": "text",
  "counterSignature": "text",
  "proof": {
    "status": "SENT",
    "statusDate": "2022-07-12T23:37:25.466566+02:00",
    "channelHash": "text",
    "senderBic": "BBBBCAXXXXX",
    "recipientBic": "CCCCESXXXXX",
    "netSettlementCollaterals": [
      {
        "type": "NATIVE",
        "amount": 0,
        "tokenSymbol": "text"
      }
    ],
    "fullySigned": true,
    "signature": "text",
    "counterSignature": "text",
    "messagesIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "endToEndIds": [
      "text"
    ],
    "created": "2022-07-12T23:37:25.466566+02:00",
    "updated": "2022-07-12T23:37:22.401717+02:00"
  },
  "created": "2022-07-12T23:37:25.466566+02:00",
  "updated": "2022-07-12T23:37:22.401717+02:00"
}

Get message proof

GEThttp://localhost:8092/api/gateway/iso20022/messages/{messageId}/proof

Path parameters

messageId*string (uuid)

Message id

Response

200400404500

Ok

Body

*/*

status*enum

Proof status

NEWCOMMITTEDAPPROVEDREJECTEDREFUNDEDVALUE_RECEIVEDSENTRECEIVEDACKNOWLEDGEDNOT_ACKNOWLEDGED

statusDate*string (date-time)

Proof status change date time

channelHash*string

Proof channel hash as hex

senderBic*string

Sender BIC

recipientBic*string

Recipient BIC

netSettlementCollaterals*array of ProofInfoCollateral (object)

Net settlement collaterals

fullySigned*boolean

Flag which tells if all parties signed a proof

signaturestring (base64)

Initiator signature

counterSignaturestring (base64)

Counterparty signature

messagesIds*array of string (uuid)

Proof's messages identifiers

endToEndIds*array of string

Proof's messages end to end identifiers

createdstring (date-time)

Proof creation date time

updatedstring (date-time)

Proof update date time

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/messages/{messageId}/proof', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "SENT",
  "statusDate": "2022-07-12T23:37:25.466566+02:00",
  "channelHash": "text",
  "senderBic": "BBBBCAXXXXX",
  "recipientBic": "CCCCESXXXXX",
  "netSettlementCollaterals": [
    {
      "type": "NATIVE",
      "amount": 0,
      "tokenSymbol": "text"
    }
  ],
  "fullySigned": true,
  "signature": "text",
  "counterSignature": "text",
  "messagesIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "endToEndIds": [
    "text"
  ],
  "created": "2022-07-12T23:37:25.466566+02:00",
  "updated": "2022-07-12T23:37:22.401717+02:00"
}

Get message payload

GEThttp://localhost:8092/api/gateway/iso20022/messages/{messageId}/payload

Path parameters

messageId*string (uuid)

Message id

Response

201400404500

Created

Body

*/*

string

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/messages/{messageId}/payload', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

"text"

Get parties

GEThttp://localhost:8092/api/gateway/iso20022/identities

Query parameters

Response

200400500

Ok

Body

*/*

content*array of PartyDto (object)

number*integer (int32)

size*integer (int32)

totalElements*integer (int64)

last*boolean

totalPages*integer (int32)

sortarray of OrderDto (object)

first*boolean

numberOfElements*integer (int32)

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/identities', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "bic": "text",
      "gatewayUrl": "text",
      "certificate": "text",
      "addresses": [
        {
          "address": "text",
          "network": "text"
        }
      ],
      "xinFinAddress": "text"
    }
  ],
  "last": false,
  "sort": [
    {
      "property": "text",
      "direction": "ASC"
    }
  ],
  "first": false
}

Get party by BIC code

GEThttp://localhost:8092/api/gateway/iso20022/identities/{bic}

Path parameters

bic*string

The bank identification code (i.e. SWIFT/BIC)

Response

200400500

Ok

Body

*/*

id*string (uuid)

Unique identifier for this party

name*string

Name of party

bic*string

Swift BIC for this party

gatewayUrl*string

URL for this party's gateway

certificate*string

Base64 encoded certificate

addresses*array of PartyAddressDto (object)

Addresses for this party

xinFinAddressstring

XinFin address

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/identities/{bic}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "bic": "text",
  "gatewayUrl": "text",
  "certificate": "text",
  "addresses": [
    {
      "address": "text",
      "network": "text"
    }
  ],
  "xinFinAddress": "text"
}

Get party accounts

GEThttp://localhost:8092/api/gateway/iso20022/identities/accounts

Query parameters

Response

200400500

Ok

Body

*/*

content*array of PartyAccountDto (object)

number*integer (int32)

size*integer (int32)

totalElements*integer (int64)

last*boolean

totalPages*integer (int32)

sortarray of OrderDto (object)

first*boolean

numberOfElements*integer (int32)

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/identities/accounts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "content": [
    {
      "iban": "text",
      "holder": "text",
      "bic": "text"
    }
  ],
  "last": false,
  "sort": [
    {
      "property": "text",
      "direction": "ASC"
    }
  ],
  "first": false
}

Get proof metrics

GEThttp://localhost:8092/api/gateway/iso20022/gateway/metrics/proof

Response

200400500

Ok

Body

*/*

last24Hours*ProofMetricsData (object)

mtd*ProofMetricsData (object)

ytd*ProofMetricsData (object)

all*ProofMetricsData (object)

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/gateway/metrics/proof', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "last24Hours": {
    "avgMessagesCount": 0,
    "avgGasUsedXdc": 0,
    "totalGasUsedXdc": 0
  },
  "mtd": {
    "avgMessagesCount": 0,
    "avgGasUsedXdc": 0,
    "totalGasUsedXdc": 0
  },
  "ytd": {
    "avgMessagesCount": 0,
    "avgGasUsedXdc": 0,
    "totalGasUsedXdc": 0
  },
  "all": {
    "avgMessagesCount": 0,
    "avgGasUsedXdc": 0,
    "totalGasUsedXdc": 0
  }
}

Get network account info

GEThttp://localhost:8092/api/gateway/iso20022/gateway/account

Response

200400500

Ok

Body

*/*

owner*string

address*string

amount*number

currency*string

Request

JavaScriptCurl

const response = await fetch('http://localhost:8092/api/gateway/iso20022/gateway/account', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "owner": "text",
  "address": "text",
  "amount": 0,
  "currency": "text"
}