Interface Message Management APIs

Last updated on Apr 10, 2026 at 10:35 PM

Within the Common APIs, the Interface Management section provides access to inbound and outbound messages exchanged between ImPAI and connected systems.

These APIs expose the original external message formats (e.g., ISO 20022 or other bank-specific formats) together with additional technical and processing metadata. The scope includes communication with internal bank systems as well as external counterparties and service providers.

The Interface Message APIs are read-only and are intended for transparency, operational monitoring, and troubleshooting purposes.

1️⃣ List Messages

The Interface Message List API is to be used to retrieve detailed information about specific messages, or request a list of existing messages.

Request Structure

❶ Query Parameters

The following request parameters can be used to filter for specific interface messages:

Field	Type	Required	Description	Constraints
`creationDateFrom`	String	No	Start date for filtering by transaction creation date.	ISO 8601 format
`creationDateTo`	String	No	End date for filtering by transaction creation date.	ISO 8601 format
`creditorAccount`	String	No	Fiter for Creditor International Bank Account Number (IBAN).	–
`creditorAgent`	String	No	Filter for Creditor's Agent BIC.	–
`creditorName`	String	No	Filter for Creditor name.	1-255 chars
`currentPage`	String	No	Filter for Page number for pagination results.	Default: 1 Starts from 1
`debtorAccount`	String	No	Fiter for Debitor International Bank Account Number (IBAN).	–
`debtorAgent`	String	No	Filter for Debtor's Agent BIC.	–
`debtorName`	String	No	Filter for Debtor name.	1-255 chars
`endToendId`	String	No	Filter for End-to-End Identification.	1-36 chars
`externalId`	String	No	Filter for External Identification.	1-36 chars
`globalId`	String	No	Filter for Global Identification.	1-36 chars
`instructionId`	String	No	Filter for Instruction Identification.	1-36 chars
`internalId`	String	No	Filter for Internal Identification.	1-36 chars
`messageId`	String	No	Filter for Message Identification.	1-36 chars
`messageType`	String	No	Filter for Message Type.	Enum: `Confirmation` `Credit` `CustomerStatus` `Instruction` `Recall` `Resolution` `Return` `StatusReport` `StatusRequest`
`messageVersion`	String	No	Filter for Message Version.	Enum: `camt.029` `camt.056` `pacs.002` `pacs.004` `pacs.008` `pacs.028` `pain.001` `pain.002`
`orderBy`	String	No	Field name to sort results by (e.g., creationDateFrom, transactionId).	Default: "startedAt"
`pageSize`	String	No	Number of transaction records to display per page.	Decimal chars >= 1 Default: 15
`receivedAtFrom`	String	No	Start date for filtering by transaction received date.	ISO 8601 format
`receivedAtTo`	String	No	End date for filtering by transaction received date.	ISO 8601 format
`requestExecutionDateFrom`	String	No	Start date for filtering by requested execution date.	ISO 8601 format
`requestExecutionDateTo`	String	No	End date for filtering by requested execution date.	ISO 8601 format
`requestId`	String	No	Filter for Request Identification.	1-36 chars
`settlementDateFrom`	String	No	Start date for filtering by transaction settlement date.	ISO 8601 format
`settlementDateTo`	String	No	End date for filtering by transaction settlement date.	ISO 8601 format
`sortOrder`	String	No	Direction to sort results (ascending or descending).	Default: `desc` Enum: `asc` `desc`
`status`	String	No	Filter for Transaction status.	Enum: `Booked` `Error` `Pending` `Received` `Rejected` `Released` `Sent`
`transactionAmountFrom`	String	No	Minimum transaction amount for filtering.	Decimal chars
`transactionAmountTo`	String	No	Maximum transaction amount for filtering.	Decimal chars
`transactionId`	String	No	Filter for Transaction Identification.	Defau1-36 chars
`type`	String	No	Filter for Type of Interface which will be also used as a partition key.	1-16 chars

Response Structure

🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`metaData`	An object containing meta information about pagination and the actual request represented by `pagination.currentPage`, `pagination.pageSize`, `pagination.totalPages`, `pagination.totalRecords`, `sort.sortBy`, `sort.sortOrder`, `filters`, `message`, and `timeStamp`
`results`	An array of objects, each one containing detail information about 1 account: `category`, `entity`, `id`, `internalCode`, `internalId`, `isoCode`, `message`, `objectReference`, `objectReferenceType`, `objectType`, `service`, `severity`, `status`, `timestamp`, and `type`

Example(s)

{
  "header": {
    "responseId": "0a816627-7899-49e4-ae47-c118d5e3cf50",
    "origRequestId": "ReqId-419578",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "metaData": {
    "pagination": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPages": 1,
      "totalRecords": 2
    },
    "sort": {
      "orderBy": [
        "CRTDAT"
      ],
      "sortOrder": [
        " desc"
      ]
    },
    "filters": { },
    "message": "Successfully retrieved 2 transactions"
  },
  "results": [
    {
      "category": "errauthentication",
      "entity": "PaymentService",
      "id": "a6172436-4431-4dac-bad0-a943396ccb75",
      "internalCode": "00T00015",
      "internalId": "1d6f5c3a-02e6-4080-995a-8a81327830f6",
      "isoCode": "EUR",
      "message": "Transaction could not completed successfully.",
      "objectReference": "PAI1500003534333",
      "objectReferenceType": "GlobalId",
      "objectType": "directory",
      "service": "common_proc",
      "severity": "fatal",
      "status": "New",
      "timestamp": "2025-06-12T15:04:05Z",
      "type": "Technical"
    }
  ]
}

🔴 Error — HTTP 400

Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and include:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "error": {
    "message": "Invalid query parameters provided"
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
`errorCode`	Application-level error identifier (e.g. `500_INTERNAL_ERROR`)
`message`	Brief description such as "Time-out" or "Something went wrong"

Example(s)

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

GET/api/common/v1/get-interfacesList available Interface Messages

2️⃣ Message Details

The Interface Message Details API is to be used to retrieve detailed information about a single specific error.

Request Structure

❶ Query Parameters

The following request parameter must be used to request a message's details:

Field	Type	Required	Description	Constraints
`id`	UUID	No	Unique identifier of the error.	–

Response Structure

🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`results`	An array of objects, each one containing detail information about 1 account: `category`, `entity`, `id`, `internalCode`, `internalId`, `isoCode`, `message`, `objectReference`, `objectReferenceType`, `objectType`, `service`, `severity`, `status`, `timestamp`, and `type`

Example(s)

{
  "header": {
    "responseId": "0a816627-7899-49e4-ae47-c118d5e3cf50",
    "origRequestId": "ReqId-419578",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "results": [
    {
      "category": "errauthentication",
      "entity": "PaymentService",
      "id": "a6172436-4431-4dac-bad0-a943396ccb75",
      "internalCode": "00T00015",
      "internalId": "1d6f5c3a-02e6-4080-995a-8a81327830f6",
      "isoCode": "EUR",
      "message": "Transaction could not completed successfully.",
      "objectReference": "PAI1500003534333",
      "objectReferenceType": "GlobalId",
      "objectType": "directory",
      "service": "common_proc",
      "severity": "fatal",
      "status": "New",
      "timestamp": "2025-06-12T15:04:05Z",
      "type": "Technical"
    }
  ]
}

🔴 Error — HTTP 400

Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and include:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "error": {
    "message": "Invalid query parameters provided"
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
`errorCode`	Application-level error identifier (e.g. `500_INTERNAL_ERROR`)
`message`	Brief description such as "Time-out" or "Something went wrong"

Example(s)

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

GET/api/common/v1/get-interface-detail/{internalId}Get Interface Message Details

Summary — Interface Message Management

The Interface Message Management section exposes two complementary endpoints:

Interface Message List API — Retrieve a list of inbound and outbound interface messages, with filtering options based on identifiers, direction, status, or time range.
Interface Message Details API — Retrieve the full external message payload and associated metadata for a specific interface message.

Together, these APIs provide:

Visibility into the technical message exchange layer between ImPAI and connected systems,
Access to the original external message formats as transmitted or received,
Contextual metadata such as direction, timestamps, processing status, and correlation identifiers,
A consistent basis for investigating integration flows and message-level issues.

The functionality is purely informational and does not alter message content, processing state, or transaction data.

1️⃣ List Messages​

2️⃣ Message Details​

Summary — Interface Message Management​

1️⃣ List Messages

2️⃣ Message Details

Summary — Interface Message Management