Skip to main content

Create a SIC IP Transaction

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

This page describes the Create APIs used to inject Swiss Interbank Clearing Instant Payment (SIC IP) messages into ImPAI.

It covers four message families:

  • Payment Instruction – initial outbound 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 message types (e.g. pain.001, camt.056, pacs.004, camt.029) as defined by the SIC Instant Payment implementation guidelines 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 validated against the applicable ISO 20022 message structures as adapted for SIC Instant Payments, including rulebook-specific 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 SIC Instant Payments by accepting (customer) requests formatted according to the ISO 20022 pain.001 message type as implemented for SIC Instant Payments. 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

Inside the paymentRequest group the following data has to be provided.

❶  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:

GroupDescription
header.responseIdUnique identifier for this response (UUID format).
header.originalRequestIdOriginal pain.001 request ID.
header.responseTimeTimestamp of response creation.
message.Document.CstmrPmtStsRptContains the resulting ISO 20022 pain.002 message structure with status details.
identifier.creditIdCredit transfer identifier.
identifier.instructionIdInstruction identifier for downstream system.

Example(s)

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

GroupDescription
headerResponse metadata containing responseId, originalRequestId, responseTime
messageAn object holding an ISO 20022 pain.002 message structure in Document.CstmrPmtStsRpt
errorStructured error with code and message
identifiersInternal transaction identifiers containing fields for creditId and instructionId

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:

GroupDescription
errorCodeApplication-level error identifier (e.g. 500_INTERNAL_ERROR)
messageBrief 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/sic-inst/v1/instruction/createCreate a Payment Instruction

2️⃣ Recall – Create​

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

Request Structure

Inside the recallRequest group the following data has to be provided.

❶  identifiers

References to the original SIC IP 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(s)

{
  "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(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"
    }
  ]
}
⬇ Try this endpoint in the Live API Explorer
POST/api/sic-inst/v1/recall/createCreate a Recall

3️⃣ Return – Create​

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

Request Structure

Inside the returnRequest group the following data has to be provided.

❶  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 SIC 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(s)

{
  "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(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"
    }
  ]
}
⬇ Try this endpoint in the Live API Explorer
POST/api/sic-inst/v1/return/createCreate a Return

4️⃣ Resolution – Create​

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

Request Structure

Inside the resolutionRequest group the following data has to be provided.

❶  identifiers

Links the resolution to the original SIC Inst transaction:

FieldTypeRequiredDescriptionConstraints
originalIdStringYesOriginal credit ID of the outgoing message linked to the SIC 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(s)

{
  "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(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"
    }
  ]
}
⬇ Try this endpoint in the Live API Explorer
POST/api/sic-inst/v1/resolution/createCreate a Resolution

Summary — Creating SIC Inst Messages​

This page explains how to create SIC Instant (SIC IP) 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 CH).

  • Recall — requests retrieval of a previously sent payment (camt.056 CH).

  • Return — reverses a settled transaction back to the originator (pacs.004 CH).

  • Resolution — communicates the final outcome of a recall investigation (camt.029 CH).

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.
Last updated on