POST /v1/iso20022/pain.002/parse

Parse a pain.002 status report and classify each rejected item as auto-retryable, HITL-required, or final.

Parses a pain.002 status report and returns one of three labels per rejected item: auto_retry (the reason code indicates a correctable issue — rebuild the payload and resubmit safely), hitl_required (the reason code requires human review — duplication, closed account), final (the rail-side outcome is terminal — do not retry).

The classification table is at apps/api/src/lib/pain002-classifier.ts and covers the ISO 20022 reason-code catalog plus common bank-extended codes (XT01..XT99).

Response includes the original reason code, the human-readable reason description, and the iso-compliant classification — the customer's queue layer decides which lane to drop the failed item into.

Request

Request body

{
  "xml": "string"
}

Response

Response body

{
  "message_id": "string",
  "original_msg_id": "string",
  "group_status": "\"ACCP\" | \"PART\" | \"RJCT\"",
  "items": "Array<{ end_to_end_id, status, reason_code?, reason_description?, classification: \"auto_retry\" | \"hitl_required\" | \"final\" }>"
}

Idempotency

Mandatory header `Idempotency-Key` (UUID or other opaque ≤64 char string). A second request with the same key and the same body returns the cached response and the header `X-Iso-Compliant-Idempotent-Replay: true`. A second request with the same key but a different body returns 409.

Rate limit

Sandbox: 60 requests / minute, 1000 / day. Production: 600 requests / minute soft cap, lifted per tenant on request.

← All docs