POST /v1/iso20022/pain.008

Build a deterministic pain.008 direct debit initiation. CORE / B2B, sequence-type enforcement, mandate metadata.

Emits a customer direct debit initiation message. SEPA CORE and B2B variants supported.

Sequence type (FRST, RCUR, OOFF, FNAL) is mandatory per transaction. The builder enforces SEPA's rule that FRST and RCUR cannot share a <PmtInf> block — split into separate PmtInfs if you have a mixed batch.

Mandate metadata (mandate_id, date_of_signature) is required and validated against ISO 8601 date format.

Response headers identical to pain.001: X-Iso-Compliant-Sha256, X-Iso-Compliant-Bank-Ruleset, X-Iso-Compliant-Msg-Id, X-Iso-Compliant-Idempotent-Replay.

See apps/api/src/routes/pain008.ts and apps/api/src/lib/pain008-builder.ts.

Request

Request body

{
  "profile": "'core' | 'b2b'",
  "bank_ruleset": "string (optional)",
  "msg_id": "string (1..35, optional)",
  "requested_collection_date": "YYYY-MM-DD",
  "creditor": "{ name, iban, bic?, address, scheme_id }",
  "collections": "Array<{ amount, currency, debtor_name, debtor_iban, debtor_bic?, debtor_address, mandate_id, date_of_signature, sequence_type, end_to_end_id, remittance? }>"
}

Response

Response body

{
  "message_id": "string",
  "xml": "string",
  "sha256": "hex string",
  "ruleset_status": "\"ok\" | \"warn\" | \"skip\"",
  "warnings": "string[]"
}

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