Transaction Management APIs

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

Within the Common APIs, the Transaction Management section provides access to transaction records processed by ImPAI, together with their related messages and associated processing information.

These APIs allow authorized users to retrieve transaction data, inspect detailed transaction information, and analyze the processing lifecycle of individual transactions. In addition to the core transaction attributes, the APIs expose historical processing events, message-level audit information, and relationships to other transactions created as part of the same workflow.

The Transaction Management APIs are read-only and are designed to support operational monitoring, investigation, and integration troubleshooting.

1️⃣ List Transactions

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

Request Structure

❶ Query Parameters

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

Field	Type	Required	Description	Constraints
`creationAtFrom`	String	No	Filter transactions created from this date and time onwards.	ISO 8601 format
`creationAtTo`	String	No	Filter transactions created up to this date and time.	ISO 8601 format
`createdBy`	String	No	Filter transactions by the name of the user who created/initiated the transaction.	1-140 chars
`creditorAccount`	String	No	Filter transactions by the creditor's International Bank Account Number (IBAN).	–
`creditorAgent`	String	No	Filter transactions by the creditor's bank BIC (Bank Identifier Code).	–
`creditorName`	String	No	Filter transactions by the name of the payment recipient (creditor).	1-140 chars
`currentPage`	String	No	Specify which page of results to retrieve when using pagination.	Decimal char, starts from 1 Default: 1
`customerId`	String	No	Filter transactions by a specific customer identifier.	1-36 chars
`debtorAccount`	String	No	Filter transactions by the debtor's International Bank Account Number (IBAN).	–
`debtorAgent`	String	No	Filter transactions by the debtor's bank BIC (Bank Identifier Code).	–
`debtorName`	String	No	Filter transactions by the name of the payment sender (debtor).	1-140 chars
`direction`	String	No	Filter transactions by payment direction relative to your institution.	Enum: `IN` `OUT`
`endToendId`	String	No	Filter transactions by End-to-End Identification.	1-36 chars
`externalId`	String	No	Filter transactions by external system identification.	1-36 chars
`globalDirection`	String	No	Filter transactions by global payment direction across all systems and networks.	Enum: `IN` `OUT`
`globalId`	String	No	Filter transactions by global identification number.	1-36 chars
`instructionId`	String	No	Filter transactions by payment instruction identification.	1-36 chars
`internalId`	String	No	Filter transactions by internal system identification.	1-36 chars
`messageId`	String	No	Filter transactions by internal system identification.	1-36 chars
`messageStatus`	String	No	Filter transactions by their current message processing status.	Enum: `ACHConfirmed` `ACHFailed` `Accepted` `AMLConfirmed` `AMLFailed` `AuthorizationFailed` `AuthorizationPending` `Authorized` `Booked` `BookingFailed` `Pending` `Processed` `RecallRejected` `Recalled` `Received` `Rejected` `ReservationFailed` `Reserved` `Returned` `RoutingConfirmed` `RoutingFailed` `Sent` `Settled` `SettlementFailed` `Validated` `ValidationFailed`
`messageType`	String	No	Filter transactions by the type of payment message.	Enum: `Confirmation` `Credit` `CustomerStatus` `Instruction` `Recall` `Resolution` `Return` `StatusReport` `StatusRequest`
`messageVersion`	String	No	Filter transactions by the ISO 20022 message version/schema used.	Enum: `camt.029` `camt.056` `pacs.002` `pacs.004` `pacs.008` `pacs.028` `pain.001` `pain.002`
`orderBy`	String	No	Specify the field name to sort the results by.	Default: `processedAt`
`originalAmount`	String	No	Filter transactions by the original transaction amount before any modifications or currency conversions.	Decimal chars
`originalMessageId`	String	No	Filter transactions by the original message identification.	1-36 chars
`originalTransactionId`	String	No	Filter transactions by the original transaction identification.	1-36 chars
`pageSize`	String	No	Specify the maximum number of transaction records to return per page.	Decimal chars >= 1 Default: 15
`processedAtFrom`	String	No	Filter transactions processed from this date and time onwards.	ISO 8601 format
`processedAtTo`	String	No	Filter transactions processed up to this date and time.	ISO 8601 format
`reasonCode`	String	No	Filter transactions by the reason code associated with the transaction.	1-4 chars, ISO 20022 conform
`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 transactions by the unique request identification.	1-36 chars
`settlementAmountFrom`	String	No	Filter transactions with settlement amount greater than or equal to this value.	Decimal chars
`settlementAmountTo`	String	No	Filter transactions with settlement amount less than or equal to this value.	Decimal chars
`settlementDateFrom`	String	No	Filter transactions with settlement date from this date and time onwards.	ISO 8601 format
`settlementDateTo`	String	No	Filter transactions with settlement date up to this date and time.	ISO 8601 format
`sortOrder`	String	No	Specify the sort direction for the orderBy field.	Default: `desc` Enum: `asc` `desc`
`sourceSystem`	String	No	Filter transactions by the source system that originated the transaction.	1-50 chars
`status`	String	No	Filter transactions by their overall processing status.	Enum: `Accepted` `Error` `InPreProcessing` `InProcessing` `Pending` `Processed` `Received` `Rejected` `Settled`
`transactionAmountFrom`	String	No	Filter transactions with transaction amount greater than or equal to this value.	Decimal chars
`transactionAmountTo`	String	No	Filter transactions with transaction amount less than or equal to this value.	Decimal chars
`transactionId`	String	No	Filter transactions by the unique transaction identification.	1-36 chars
`updatedBy`	String	No	Filter transactions by the user or system that last updated the transaction record.	1-140 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 transaction: `createdAt`, `createdBy`, `creditorAccount`, `creditorAgent`, `creditorName`, `customerId`, `debtorAccount`, `debtorAgent`, `debtorName`, `direction`, `endToendId`, `externalId`, `globalDirection`, `globalId`, `instructionId`, `internalId`, `messageId`, `messageStatus`, `messageType`, `messageVersion`, `originalAmount`, `messageID`, `originalMessageId`, `originalTransactionId`, `processedAt`, `reasonCode`, `requestExecutionDate`, `requestId`, `settlementAmount`, `settlementCurrency`, `settlementDate`, `sourceSystem`, `status`, `transactionAmount`, `transactionCurrency`, `transactionId`, `updatedAt`, `updatedBy`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "metaData": {
    "pagination": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPages": 1,
      "totalRecords": 2
    },
    "sort": {
      "orderBy": "transactionAmount",
      "sortOrder": "asc"
    },
    "filters": { },
    "message": "Successfully retrieved 2 transactions"
  },
  "results": [
    {
      "createdAt": "2025-03-31 09:01:06.543615+02",
      "createdBy": "Marilyn Monroe",
      "creditorAccount": "DE380019000500000000263180002",
      "creditorAgent": "COBADEFFXXX",
      "creditorName": "John Doe",
      "customerId": "CUST001542025040300078",
      "debtorAccount": "DE380019000500000000263180002",
      "debtorAgent": "string",
      "debtorName": "Jane Smith",
      "direction": "IN",
      "endToendId": "E2E001542025040300078",
      "externalId": "EXT001542025040300078",
      "globalDirection": "OUT",
      "globalId": "GLB001542025040300078",
      "instructionId": "INSTR001542025040300078",
      "internalId": "INT001542025040300078",
      "messageId": "MSG001542025040300078",
      "messageStatus": "Settled",
      "messageType": "Return",
      "messageVersion": "pain.001.001.09",
      "originalAmount": 100.5,
      "messageID": "MSG-123456789",
      "originalMessageId": "ORIG-MSG-123456789",
      "originalTransactionId": "ORIG-TXN-123456789",
      "processedAt": "2025-03-31 09:01:06.543615+02",
      "reasonCode": "AC01",
      "requestExecutionDate": "2025-03-31",
      "requestId": "REQ-123456789",
      "settlementAmount": 100.5,
      "settlementCurrency": "EUR",
      "settlementDate": "2025-03-31",
      "sourceSystem": "CORE_BANKING",
      "status": "InPreProcessing",
      "transactionAmount": 5000.5,
      "transactionCurrency": "EUR",
      "transactionId": "PAI1500003315188",
      "updatedAt": "2025-03-31 09:01:06.543615+02",
      "updatedBy": "John Doe"
    }
  ]
}

🔴 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-transactionsList available Transactions

2️⃣ Transaction Details

The Transaction Details API is to be used to retrieve detailed information about a single specific transaction.

Request Structure

❶ Query Parameters

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

Field	Type	Required	Description	Constraints
`internalId`	UUID	No	Internal identification of the transaction.	–

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-transaction-detail/{Id}Get Transaction Details

3️⃣ Transaction History

The Transaction History API is used to retrieve the chronological history of events and state changes associated with a specific transaction.

Request Structure

❶ Query Parameters

The following request parameter must be used to request a transaction's history:

Field	Type	Required	Description	Constraints
`globalId`	UUID	Yes	Global identification of the transaction.	–
`globalDirection`	String	No	Global direction of the transaction.	Enum: `IN` `OUT`

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 object containing detail information about the transaction: `createdAt`, `direction`, `globalDirection`, `globalId`, `id`, `internalId`, `messageType`, `messageVersion`, `status`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "results": {
    "createdAt": "2025-06-03T14:46:58Z",
    "direction": "IN",
    "globalDirection": "IN",
    "globalId": "GLB001542025040300078",
    "id": "91ac4256-8591-4205-841e-bf1dbdb1135e",
    "internalId": "INT001542025040300078",
    "messageType": "Confirmation",
    "messageVersion": "camt.029",
    "status": "Accepted"
  }
}

🔴 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-transaction-history/{globalId}/{globaldirection}Fetch Transaction History Details

4️⃣ Transaction Audit

The Transaction Audit API is to be used to retrieve audit trail about a single specific transaction.

Request Structure

❶ Query Parameters

The following request parameter must be used to request a transaction's audit information:

Field	Type	Required	Description	Constraints
`internalId`	UUID	Yes	Internal identification of the transaction.	1-36 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 `auditSource`, `message`, `timestamp`, `totalRecords`, and `transactionId`
`transactionAudit`	An array of audit records for the requested transaction: `data`, `id`, `operation`, `parentId`, `revision`, `serviceName`, `timestamp`, and `user`

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "metaData": {
    "auditSource": "TransactionAudit",
    "message": "Successfully retrieved 5 audit records",
    "timestamp": "2025-04-14T07:30:00Z",
    "totalRecords": 5,
    "transactionId": "INT001542025040300078"
  },
  "transactionAudit": [
    {
      "data": "{\"status\":\"pending\",\"amount\":1500.75}",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "operation": "CREATE",
      "parentId": "987fcdeb-51a2-43d7-8a4f-567890123456",
      "revision": 1,
      "serviceName": "SCT_INST_PROC",
      "timestamp": "2025-03-31T09:01:06.543615Z",
      "user": "system_user"
    }
  ]
}

🔴 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-transaction-audit/{Id}Fetch Transaction Audit Trail

The Transaction Details API is to be used to retrieve detailed information about a single specific transaction.

Request Structure

❶ Query Parameters

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

Field	Type	Required	Description	Constraints
`globalId`	UUID	Yes	Global identification of the transaction.	1-36 chars
`internalId`	UUID	Yes	Internal identification of the transaction.	1-36 chars
`globalDirection`	String	Yes	Global direction of the transaction.	Enum: `IN` `OUT`

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 one related message: createdAt, createdBy, creditorAccount, creditorAgent, creditorName, customerId, debtorAccount, debtorAgent, debtorName, direction, endToendId, externalId, globalDirection, globalId, instructionId, internalId, messageId, messageStatus, messageType, messageVersion, originalAmount, originalMessageId, originalTransactionId, processedAt, reasonCode, requestExecutionDate, requestId, settlementAmount, settlementCurrency, settlementDate, sourceSystem, status, transactionAmount, transactionCurrency, transactionId, updatedAt, and updatedBy

Example(s)

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "results": [
    {
      "createdAt": "2025-03-31 09:01:06.543615+02",
      "createdBy": "Marilyn Monroe",
      "creditorAccount": "DE380019000500000000263180002",
      "creditorAgent": "COBADEFFXXX",
      "creditorName": "John Doe",
      "customerId": "CUST001542025040300078",
      "debtorAccount": "DE380019000500000000263180002",
      "debtorAgent": "string",
      "debtorName": "Jane Smith",
      "direction": "IN",
      "endToendId": "E2E001542025040300078",
      "externalId": "EXT001542025040300078",
      "globalDirection": "OUT",
      "globalId": "GLB001542025040300078",
      "instructionId": "INSTR001542025040300078",
      "internalId": "INT001542025040300078",
      "messageId": "MSG001542025040300078",
      "messageStatus": "Settled",
      "messageType": "Return",
      "messageVersion": "pain.001.001.09",
      "originalAmount": 100.5,
      "originalMessageId": "ORIG-MSG-123456789",
      "originalTransactionId": "ORIG-TXN-123456789",
      "processedAt": "2025-03-31 09:01:06.543615+02",
      "reasonCode": "AC01",
      "requestExecutionDate": "2025-03-31",
      "requestId": "REQ-123456789",
      "settlementAmount": 100.5,
      "settlementCurrency": "EUR",
      "settlementDate": "2025-03-31",
      "sourceSystem": "CORE_BANKING",
      "status": "InPreProcessing",
      "transactionAmount": 5000.5,
      "transactionCurrency": "EUR",
      "transactionId": "PAI1500003315188",
      "updatedAt": "2025-03-31 09:01:06.543615+02",
      "updatedBy": "John Doe"
    }
  ]
}

🔴 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-related-transactions/{globalId}/{internalId}/{globalDirection}Get Transaction Details

Summary — Transaction Management

The Transaction Management section exposes several complementary endpoints:

Transaction List API — Retrieve a list of transactions with filtering options based on identifiers, status, scheme, or time range.
Transaction Details API — Retrieve detailed information for a specific transaction.
Transaction History API — Retrieve the chronological history of processing events and state changes for a transaction.
Transaction Audit API — Retrieve the message-level audit trail recorded during transaction processing.
Related Transactions API — Retrieve transactions that are logically related within the same processing workflow.

Together, these APIs provide:

A centralized view of transactions processed by ImPAI,
Detailed insight into transaction data and processing state,
Access to historical processing events and audit information,
Visibility into relationships between transactions within a workflow.

The functionality is purely informational and does not modify transaction state or message data.

1️⃣ List Transactions​

2️⃣ Transaction Details​

3️⃣ Transaction History​

4️⃣ Transaction Audit​

5️⃣ Related Messages​

Summary — Transaction Management​

1️⃣ List Transactions

2️⃣ Transaction Details

3️⃣ Transaction History

4️⃣ Transaction Audit

5️⃣ Related Messages

Summary — Transaction Management