Create a Transaction

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

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:

Field	Type	Required	Description	Constraints
`externalId`	String	Yes	External 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:

Field	Description
`header.responseId`	Unique identifier for this response (UUID format).
`header.origRequestId`	Original pain.001 request ID.
`header.responseTime`	Timestamp of response creation
`message.Document.CstmrPmtStsRpt`	Contains the resulting ISO 20022 pain.002 message structure with status details.
`identifiers.creditId`	Credit transfer identifier.
`identifiers.instructionId`	Instruction identifier for downstream system.

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
    }
  },
  "identifiers": {
    "creditId": "PAI1500000018805",
    "instructionId": "PAI1500000019002"
  }
}

🔴 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`
`message`	An object holding an ISO 20022 pain.002 message structure in `Document.CstmrPmtStsRpt`
`error`	Structured error with `code` and `message`
`identifiers`	Internal transaction identifiers containing fields for `creditId` and `instructionId`

Example(s)

{
  "header": {
    "responseId": "00000000-0000-0000-0000-000000000000",
    "originalRequestId": "ReqId-Example",
    "responseTime": "2025-01-01T00:00:00Z"
  },
  "message": {
    "Document": {
      "CstmrPmtStsRpt": {
        // ISO 20022 pain.002 message structure with status details
      }
    }
  },
  "error": {
    "message": "Invalid request"
  }
  "identifiers": {
    "creditId": "PAI000000011111",
    "instructionId": "PAI000000011110"
  }
}

🟡 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

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:

Field	Type	Required	Description	Constraints
`originalId`	String	Yes	Identifier 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:

Field	Type	Required	Description	Constraints
`recallReason`	String	Yes	Reason 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`
`additionalInformation`	String[]	No	Additional 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:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`success`	An 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:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`
`fields`	An array listing field-level issues (`fieldMap`, `reasonCode`, `reasonText`)

Example(s)

{
  "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:

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

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:

Field	Type	Required	Description	Constraints
`originalId`	String	Yes	Original 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:

Field	Type	Required	Description	Constraints
`returnReason`	String	Yes	Reason code for the return.	Enum: `FOCR`
`additionalInformation`	String[]	No	Additional 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:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`success`	An 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:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`
`fields`	An array listing field-level issues (`fieldMap`, `reasonCode`, `reasonText`)

Example(s)

{
  "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:

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

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:

Field	Type	Required	Description	Constraints
`originalId`	String	Yes	Original 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):

Field	Type	Required	Description	Constraints
`rejectReason`	String	Yes	Reason code for rejecting the cancellation request.	Enum: `AC04` `AM04` `ARDT` `CUST` `LEGL` `NOAS` `NOOR`
`additionalInformation`	String	Yes	Additional 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:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`success`	An 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:

Group	Description
`header`	Response metadata containing `responseId`, `originalRequestId`, `responseTime`
`error`	An object with a human-readable description in `message`
`fields`	An array listing field-level issues (`fieldMap`, `reasonCode`, `reasonText`)

Example(s)

{
  "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:

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

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 follows the same high-level pattern (validate → correlate → persist → respond), but the input differs by message type:

Create Instruction expects the full ISO 20022 message payload (wrapped in JSON), validates it, correlates it to the lifecycle, creates the internal transaction, and returns technical identifiers plus the appropriate ISO 20022 response/status data.
Create Recall / Return / Resolution do not submit a full ISO 20022 message. Instead, they provide a reference to the underlying transaction/message plus the required reason information. ImPAI validates the reference and reason, correlates it to the existing lifecycle, creates the corresponding internal record, and returns technical identifiers plus status/response information.

Shared Behaviour of Create APIs​

1️⃣ Payment Instruction – Create​

2️⃣ Recall – Create​

3️⃣ Return – Create​

4️⃣ Resolution – Create​

Summary — Creating SCT Inst Messages​

Shared Behaviour of Create APIs

1️⃣ Payment Instruction – Create

2️⃣ Recall – Create

3️⃣ Return – Create

4️⃣ Resolution – Create

Summary — Creating SCT Inst Messages