Process Payment Validation

---

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 an SCT Inst 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 GrpHdr, PmtInf, and CdtTrfTxInf, must be provided.

Request Structure

The request must contain:

❶ paymentRequest

The root object containing the Document element of the pain.001 message.

Inside the Document, the element CstmrCdtTrfInitn must contain:

• GrpHdr — general message metadata
• PmtInf — payment information group(s)
• CdtTrfTxInf — transaction details

Multiple transactions per request are supported.

Example Request:

{
  "paymentRequest": {
    "Document": {
      "CstmrCdtTrfInitn": {
        "GrpHdr": {
          ...
        },
        "PmtInf": [
          {
            ...
          }
        ]
      }
    }
  }
}

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 containing the actual success status

Example:

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

Group	Description
header	Response metadata including responseId, originalRequestId, and responseTime.
error	Contains the primary error message returned by the system (message).
errors	Array of detailed validation issues, each specifying the affected field (fieldMap), the error code (reasonCode), and a human-readable description (reasonText).

Example:

{
  "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"
    }
  ]
}

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

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

POST/api/sct-inst/v1/instruction/prevalidateValidate Field Content

---

Summary — Handling Validation

The Pre-Validation API allows external systems to verify an SCT Inst 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 Payment Instruction (pain.001 → pacs.008)

note

This helps prevent lifecycle failures and significantly improves integration reliability.