Skip to main content

Create a Transaction


This page describes the Create APIs used to inject SEPA Instant (SCT Inst) messages into ImPAI.

It covers four message families:

  • Payment Instruction – initial outgoing customer credit transfer.
  • Recall – request to pull back a previously sent payment.
  • Return – reversal of a settled payment back to the originator.
  • Resolution – final outcome of a recall or investigation.

Each API uses a message-specific request model aligned with the corresponding ISO 20022 schema (e.g. pain.001, camt.056, pacs.004, camt.029) and returns identifiers and status information used throughout the transaction lifecycle.


Shared Behaviour of Create APIs​

Across all four Create operations, the following behaviour is common:

  • Single-message processing – each request creates exactly one logical message instance.
  • Validation – payloads are checked against ISO 20022 schemas and SCT Inst rulebook constraints.
  • Identifier enrichment – ImPAI assigns internal / global identifiers for tracking, UI navigation, and audit.
  • Workflow integration – successful messages are forwarded into the appropriate processing flow (clearing, posting, investigation, etc.).
  • Structured responses – responses contain traceable IDs and, where applicable, ISO 20022-based status information.

1️⃣ Payment Instruction – Create​

This RESTful service initiates SEPA Instant payments by accepting requests formatted according to the ISO 20022 pain.001 standard. It validates the instruction, creates a new transaction record, and prepares the payment for subsequent lifecycle steps (approval, clearing, settlement).

info

Each request may contain only one payment instruction to simplify tracing and error handling.


Request Structure

❢  identifiers

Business-level references linking the payment instruction to external systems:

FieldTypeRequiredDescriptionConstraints
externalIdStringYesExternal reference for the payment, typically provided by the initiating system. Used for matching responses and client-side tracking.1–36 chars

❷  Document

The Document contains the actual payment instruction CstmrCdtTrfInitn in ISO 20022 pain.001 format, including:

  • Group Header (GrpHdr): message ID, creation time, transaction count, initiating party.
  • Payment Information (PmtInf): debtor, payment type, execution date, amount, creditor details, etc.
note

The full structure and validation rules are defined in the ISO 20022 pain.001 specification and enforced via the Swagger definition.

Response Structure
🟒 Success β€” HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

FieldDescription
headerTechnical response metadata.
header.responseIdUnique identifier for this response (UUID format).
header.origRequestIdOriginal pain.001 request ID.
message.DocumentISO 20022 pain.002 status report.
message.Document.CstmrPmtStsRptContains the resulting ISO 20022 pain.002 message structure with status details.

Example:

{
"header": {
"responseId": "603027ad-1047-43a3-b89b-03ff75fc8af9",
"originalRequestId": "ReqId-833583220015",
"responseTime": "2025-06-02T14:15:22Z"
},
"message": {
"Document": {
// ISO 20022 pain.002 customer payment status report
}
}
}
πŸ”΄ Error β€” HTTP 400

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

GroupDescription
headerResponse metadata containing responseId, originalRequestId, responseTime
errorAn object with a human-readable description in message
fieldsAn array listing field-level issues (fieldMap, reasonCode, reasonText)

Example:

{
"header": {
"responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"error": {
"message": "Invalid message received : credit not found"
},
"fields": [
{
"fieldmap": "/Document/CstmrCdtTrfInitn/PmtInf/0/CdtTrfTxInf/0/UltmtCdtr/Id/OrgId",
"reasoncode": "FF01",
"reasontext": "expected string, but got object"
}
]
}
🟑 Error β€” HTTP 500

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

GroupDescription
errorCodeApplication-level error identifier (e.g. 500_INTERNAL_ERROR)
messageBrief description such as "Time-out" or "Something went wrong"

Example:

{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
POST/api/sct-inst/v1/instruction/createCreate a Payment Instruction

2️⃣ Recall – Create​

This service creates Recall messages for SCT Inst payments. It generates an ISO 20022 camt.056 message to request a recall of a previously sent payment.

Request Structure

❢  identifiers

References to the original SCT Inst transaction:

FieldTypeRequiredDescriptionConstraints
originalIdStringYesIdentifier of the original credit transaction to be recalled. Must reference an existing payment in a recallable state.1–36 chars

❷  RecallDetails

Reason and optional additional context:

FieldTypeRequiredDescriptionConstraints
recallReasonStringYesReason code for cancellation.
For DS-05 recall, codes DUPL and TECH can only be used within 10 banking business days, and code FRAD within 13 months.
Codes CUST, AC03, and AM09 refer to DS-08 recall from originator (debtor) – FRFO (Request for Recall by the Originator).
Enum:
DUPL
FRAD
TECH
AC03
AM09
CUST
additionalInformationString[]NoAdditional context or clarification for the recall. Each string may be up to 105 characters.Array of max. 105-char strings
Response Structure
🟒 Success β€” HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

GroupDescription
headerA group containing responseId, originalRequestId, responseTime
successAn object with detailed information like status and a group of identifiers of the created message

Example:

{
"header": {
"responseId": "3a7ee3f3-1e5e-45ea-87dc-aae4442409c5",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"success": {
"status": "Success",
"identifiers": {
"recallId": "PAI1500004121533"
}
}
}
πŸ”΄ Error β€” HTTP 400

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

GroupDescription
headerResponse metadata containing responseId, originalRequestId, responseTime
errorAn object with a human-readable description in message
fieldsAn array listing field-level issues (fieldMap, reasonCode, reasonText)

Example:

{
"header": {
"responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"error": {
"message": "Invalid message received : credit not found"
},
"fields": [
{
"fieldmap": "/Document/CstmrCdtTrfInitn/PmtInf/0/CdtTrfTxInf/0/UltmtCdtr/Id/OrgId",
"reasoncode": "FF01",
"reasontext": "expected string, but got object"
}
]
}
🟑 Error β€” HTTP 500

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

GroupDescription
errorCodeApplication-level error identifier (e.g. 500_INTERNAL_ERROR)
messageBrief description such as "Time-out" or "Something went wrong"

Example:

{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
POST/api/sct-inst/v1/recall/createCreate a Recall

3️⃣ Return – Create​

This RESTful service handles interbank Return processing for SCT Inst payments. It creates an ISO 20022 pacs.004 Return message to reverse a previously settled credit transfer.

Request Structure

❢  identifiers

The identifiers section provides references to previously created payment messages and links the return request to the original transaction:

FieldTypeRequiredDescriptionConstraints
originalIdStringYesOriginal credit ID of the outgoing SCT Inst message. Only one return is allowed per underlying transaction and only for suitable statuses.1–36 chars

❷  ReturnDetails

The ReturnDetails section defines the reason for the return and any additional context:

FieldTypeRequiredDescriptionConstraints
returnReasonStringYesReason code for the return.Enum:
FOCR
additionalInformationString[]NoAdditional context or clarification for the return.Array of strings (max. length per item: 105)
Response Structure
🟒 Success β€” HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

GroupDescription
headerA group containing responseId, originalRequestId, responseTime
successAn object with detailed information like status and a group of identifiers of the created message

Example:

{
"header": {
"responseId": "3a7ee3f3-1e5e-45ea-87dc-aae4442409c5",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"success": {
"status": "Success",
"identifiers": {
"transactionId": "EXT123456"
}
}
}
πŸ”΄ Error β€” HTTP 400

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

GroupDescription
headerResponse metadata containing responseId, originalRequestId, responseTime
errorAn object with a human-readable description in message
fieldsAn array listing field-level issues (fieldMap, reasonCode, reasonText)

Example:

{
"header": {
"responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"error": {
"message": "Invalid message received : credit not found"
},
"fields": [
{
"fieldmap": "/Document/CstmrCdtTrfInitn/PmtInf/0/CdtTrfTxInf/0/UltmtCdtr/Id/OrgId",
"reasoncode": "FF01",
"reasontext": "expected string, but got object"
}
]
}
🟑 Error β€” HTTP 500

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

GroupDescription
errorCodeApplication-level error identifier (e.g. 500_INTERNAL_ERROR)
messageBrief description such as "Time-out" or "Something went wrong"

Example:

{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
POST/api/sct-inst/v1/return/createCreate a Return

4️⃣ Resolution – Create​

This RESTful service creates Resolution of Investigation messages for SCT Inst flows. It generates an ISO 20022 camt.029 message to communicate the final outcome of a recall or investigation.

Request Structure

❢  identifiers

Links the resolution to the original SCT Inst transaction:

FieldTypeRequiredDescriptionConstraints
originalIdStringYesOriginal credit ID of the outgoing message linked to the SCT Inst transaction.1–36 chars

❷  ResolutionDetails

The ResolutionDetails section provides the reason and any additional context for the resolution (e.g. rejection of the recall request):

FieldTypeRequiredDescriptionConstraints
rejectReasonStringYesReason code for rejecting the cancellation request.Enum:
AC04
AM04
ARDT
CUST
LEGL
NOAS
NOOR
additionalInformationStringYesAdditional context or explanation for the resolution. Each item must be a string of max 105 characters.Array of strings (max. length per item: 105)
Response Structure
🟒 Success β€” HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

GroupDescription
headerA group containing responseId, originalRequestId, responseTime
successAn object with detailed information like status and a group of identifiers of the created message

Example:

{
"header": {
"responseId": "3a7ee3f3-1e5e-45ea-87dc-aae4442409c5",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"success": {
"status": "Success",
"identifiers": {
"transactionId": "PAI1500004121533"
}
}
}
πŸ”΄ Error β€” HTTP 400

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

GroupDescription
headerResponse metadata containing responseId, originalRequestId, responseTime
errorAn object with a human-readable description in message
fieldsAn array listing field-level issues (fieldMap, reasonCode, reasonText)

Example:

{
"header": {
"responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
"originalRequestId": "ReqId-419578",
"responseTime": "2025-06-02T14:15:22Z"
},
"error": {
"message": "Invalid message received : credit not found"
},
"fields": [
{
"fieldMap": "/Document/CstmrCdtTrfInitn/PmtInf/0/CdtTrfTxInf/0/UltmtCdtr/Id/OrgId",
"reasonCode": "FF01",
"reasonText": "expected string, but got object"
}
]
}
🟑 Error β€” HTTP 500

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

GroupDescription
errorCodeApplication-level error identifier (e.g. 500_INTERNAL_ERROR)
messageBrief description such as "Time-out" or "Something went wrong"

Example:

{
"errorCode": "500_INTERNAL_ERROR",
"message": "Something went wrong"
}
POST/api/sct-inst/v1/resolution/createCreate a Resolution

Summary β€” Creating SCT Inst Messages​

This page explains how to create SEPA Instant (SCT Inst) messages in ImPAI.
All Create APIs accept a single structured ISO 20022 message, validate it, link it to the payment lifecycle, and generate the corresponding interbank message.

The system supports four creation flows:

  • Payment Instruction β€” creates an outgoing customer payment (pain.001 β†’ pacs.008).

  • Recall β€” requests retrieval of a previously sent payment (camt.056).

  • Return β€” reverses a settled transaction back to the originator (pacs.004).

  • Resolution β€” communicates the final outcome of a recall investigation (camt.029).

Each Create operation:

  • expects message-specific data (ISO 20022 wrapped in JSON),
  • performs validation and lifecycle correlation,
  • creates the internal transaction record,
  • and returns technical identifiers plus ISO 20022 response or status data.