POST /v1/iso20022/pain.001

Build a deterministic pain.001 credit transfer initiation. Structured-address enforced under post-mandate rulesets.

Emits a customer credit transfer initiation message. Deterministic XML — given the same idempotency key + body, the output bytes are identical.

The request maps to one or more <PmtInf> blocks. The default is one PmtInf for the whole batch (canonical SEPA payroll shape); split across multiple PmtInf when you have different requested execution dates or different debit accounts.

Structured-address enforcement: under any rule pack that flags structuredAddressRequired, the builder rejects payments whose debtor / creditor address is carried in address_line and demands the structured street_name / building_number / post_code / town_name / country form. This is the SWIFT Nov 14, 2026 mandate path.

Response headers: X-Iso-Compliant-Sha256 (audit), X-Iso-Compliant-Bank-Ruleset (echo), X-Iso-Compliant-Msg-Id (deterministic MsgId), X-Iso-Compliant-Idempotent-Replay (cache hit).

See apps/api/src/routes/pain001.ts and the builder at apps/api/src/lib/pain001-builder.ts.

Request

Request body

{
  "scope": "'pain.001.001.09' | 'pain.001.001.09.ch.03' (optional)",
  "profile": "'ch_2019' | 'cgi_mp' | 'sepa' (optional)",
  "bank_ruleset": "string (3..64, optional; e.g. \"ubs-ch@2026.06\")",
  "msg_id": "string (1..35, optional; derived if absent)",
  "requested_execution_date": "YYYY-MM-DD",
  "initiating_party": "{ name, iban?, bic?, address }",
  "debtor": "{ name, iban, bic?, address }",
  "payments": "Array<{ amount, currency, creditor_name, creditor_iban, creditor_bic?, creditor_address, remittance?, end_to_end_id, service_level? }>"
}

Response

Response body

{
  "message_id": "string",
  "xml": "string (full pain.001 XML)",
  "sha256": "hex string",
  "ruleset_status": "\"ok\" | \"warn\" | \"skip\"",
  "warnings": "string[]"
}

Example

curl

curl -sS https://api.iso-compliant.com/v1/iso20022/pain.001 \
  -H 'Authorization: Bearer iso_live_…' \
  -H 'Idempotency-Key: 8f1ea2…' \
  -H 'Content-Type: application/json' \
  -d @payroll.json

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