Skip to main content

Process Payment Validation

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

This section describes the Pre-Validation API provided by ImPAI. It performs the same syntactic and semantic checks that ImPAI applies internally when a payment is manually submitted. This API allows client systems to validate an ISO 20022 pain.001 message before initiating a SIC IP transaction.

The validation service exposes a single endpoint:

  • Pre-Validation Request — verifies a full pain.001 Customer Credit Transfer Initiation message.

1️⃣ Pre-Validation Request​

The Pre-Validation API accepts a complete paymentRequest structure containing an ISO 20022 pain.001 Document. All mandatory groups, such as identifiers and Document, must be provided.

Request Structure

The request must contain:

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

Multiple transactions per request are supported.


Example Request:

{
  "paymentRequest": {
    "identifiers": {
      "externalId": "EXTID_4987451120"
    },
    "Document": {
      "CstmrCdtTrfInitn": {
        "GrpHdr": {
          ...
        },
        "PmtInf": [
          {
            ...
          }
        ]
      }
    }
  }
}
Response Structure
🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

GroupDescription
headerA group containing responseId, originalRequestId, responseTime
successAn object containing the actual success status

Example(s)

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-05-30T10:45:31.002Z"
  },
  "success": {
    "status": "Success",
  }
}
🔴 Error — HTTP 400

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

GroupDescription
headerResponse metadata including responseId, originalRequestId, and responseTime.
errorContains the primary error message returned by the system (message).
errorsArray of detailed validation issues, each specifying the affected field (fieldMap), the error code (reasonCode), and a human-readable description (reasonText).

Example(s)

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-05-30T10:45:31.002Z"
  },
  "error": {
    "message": "Validation failed"
  },
  "errors": [
    {
      "fieldMap": "CstmrCdtTrfInitn.PmtInf.CdtTrfTxInf.Amt.InstdAmt",
      "reasonCode": "INVALID_FORMAT",
      "reasonText": "Amount format is invalid"
    }
  ]
}
⬇ Try this endpoint in the Live API Explorer
POST/api/sic-inst/v1/instruction/prevalidateValidate Field Content

Summary — Handling Validation​

The Pre-Validation API allows external systems to verify a SIC Instant Payment before submitting it.
It ensures that:

  • the pain.001 message is syntactically correct,
  • all mandatory ISO 20022 elements are present and valid,
  • ImPAI-specific rules (amounts, identifiers, structure) are respected,
  • and the transaction can be safely processed by the Create API.

Use this endpoint to perform all safety checks before invoking the following operations:

  • Create Swiss Payment Instruction (pain.001 → pacs.008)
note

This helps prevent lifecycle failures and significantly improves integration reliability.

Last updated on