Validation reference

When a payment is rejected, the reasons come back as a list of issues in error.details.issues, under 422 and under 400 alike, so one parse handles both. This is what the engine sends for a USD payment on a SEPA rail:

{
  "code": "PAYMENT_TYPE_SEPA_EUR_ONLY",
  "level": "payment-type",
  "bank": "deutsche-bank-be",
  "paymentType": "sepa",
  "path": "payments[0].transactions[0].currency",
  "message": "SEPA is a EUR scheme; got USD. Use \"international\" for non-EUR cross-border payments."
}

• severity is warning for a warning and omitted for an error. An issue with no severity blocks the payment; a warning never does.
• level is the stage that raised the issue: generic, bank or payment-type. bank and paymentType appear when the rule belongs to one.

Validation has three levels and returns every issue at once. The exception is a schema failure: if the JSON does not match the canonical schema you get only GENERIC_SCHEMA_* issues, because nothing else can run.

1. Generic rules: schema, currency, amount, dates, references.
2. Bank rules: what one bank requires, such as a BIC or a national account-number check.
3. Payment-type rules: what one payment type requires, such as SEPA being EUR-only.

A schema failure is 422 on BankConnector-Version: 2026-08-25 and later, and 400 on 2026-06-01 and with no version header (see the changelog). A body that is not JSON at all is 400. POST /api/validate/{bank} reports instead of refusing: it answers 200 with valid: false and the issues, and only an older version pin gets the 400 for a schema failure.

An unknown field is stripped, not rejected. The only signal is the warning UNKNOWN_FIELD_DROPPED, with the path of the field that was dropped.

POST /api/convert/{bank}?validate=true also validates the generated pain.001 against its schema. A failure is a 422 whose issues are XSD_INVALID.

Generic rules

The id checks cover one request, not earlier ones. Banks de-duplicate on these ids and can silently drop a repeat, so the engine refuses it first. For repeat submissions across requests see Idempotency.

Date rules use the company's timezone, not UTC. A call that names no single company is judged in UTC.

Cut-off times

A bank stops taking same-day orders at a deadline it publishes. GENERIC_EXECUTION_DATE_AFTER_CUTOFF is a warning, never a refusal: it names the deadline and the current time in the bank's zone. It only exists for a bank whose cut-off BankConnector holds, so its absence does not mean you are inside the deadline. Check with your bank.

Profile warnings

A bank profile is BankConnector's description of one bank: its character set, field lengths and payment types.

Two profile codes are errors:

• PROFILE_NAME_UNREPRESENTABLE: a required name becomes empty after transliteration (CJK only, for example).
• SEPA_ID_SLASH_INVALID: on a SEPA payment, an id starts or ends with / or contains //.

Transliteration runs before truncation and can lengthen text (ä becomes ae), so a name that looks short can still be truncated.

Bank rules

Per-bank rules are not listed here. Each issue's own message names the bank's requirement, and GET /api/banks/{bank}/payment-types returns what that bank expects before you build against it. The codes you meet most:

• BANK_BIC_REQUIRED: this bank requires the debtor BIC.
• BANK_DEBTOR_COUNTRY_REQUIRED: this bank requires debtor.country.
• BANK_BBAN_CHECKSUM_INVALID: a national account number fails its check digit.
• REGULATORY_REPORTING_REQUIRED (error): a cross-border payment out of Norway above NOK 100 000 or Sweden above SEK 150 000, in that currency, with no regulatoryReporting.details[].code. The rule and its code list come from regulatoryReporting on GET /api/banks/{bank}/payment-types.
• REGULATORY_REPORTING_EXPECTED (warning): the same duty on a payment in a third currency. The engine holds no exchange rates and compares the bare number, so EUR 50 000 out of Norway raises nothing. Convert it yourself.
• BANK_ADDRESS_DERIVATION_*: only when the bank settings turn on deriveHybridAddress, which takes the postcode and town from an address line for DE, AT, FI, FR, NL, GB, JE, GG and IM. When it cannot do that with certainty the payment is refused and the issue says why. Supplying postalAddress.townName avoids all of them.

Payment-type rules

Examples only; a bank offers about 26 types in all. GET /api/banks/{bank}/payment-types lists the ones it offers.

If you omit paymentType, the engine picks one: POST /api/convert/{bank} reports it in the X-Auto-Payment-Type header and POST /api/convert-async/{bank} in autoPaymentType. If it cannot (PAYMENT_TYPE_AUTO_UNRESOLVED) or the bank does not offer the type (PAYMENT_TYPE_NOT_OFFERED), you get an error; set the type explicitly when in doubt. PAYMENT_TYPE_SEPA_DEBTOR_OUTSIDE_SEPA means a SEPA payment's debtor IBAN is from outside the SEPA area; use international.

Where warnings are returned

A warning never blocks. It reports a file the bank will accept while doing something other than what you asked, such as sending an urgent payment at normal speed. Warnings arrive on success responses too:

warnings holds the same issue objects as issues, filtered to warnings. The convert header carries codes only, as CODE=count pairs: X-Validation-Warnings: SEPA_INSTRPRTY_IGNORED=1,PROFILE_NAME_TRUNCATED=3. For the messages and paths, post the same body to POST /api/validate/{bank}.

Handling issues in your client

// Rejected: a rule failure is 422, and a schema failure is 400 on an older version pin.
if (res.status === 422 || res.status === 400) {
  const { error } = await res.json();
  const issues = error.details?.issues ?? [];
  const blocking = issues.filter((i: any) => i.severity !== "warning");
  const warnings = issues.filter((i: any) => i.severity === "warning");
  // Surface `blocking` to whoever owns the payment data; log `warnings`.
}

// Accepted: the payment went through; log anything it warned about.
if (res.status === 201) {
  const { journalNo, warnings = [] } = await res.json();
  for (const w of warnings) console.warn(`${journalNo} ${w.code} @ ${w.path}: ${w.message}`);
}

Treat errors as "fix and resubmit" and warnings as "worth logging". A truncation or non-banking-day warning is often the first sign of a data-quality problem upstream.

A bank with no rails refuses the payment

A bank profile with no payment types has no rail a payment could use. A payment to it is refused with the error PAYMENT_TYPE_BANK_OFFERS_NO_PAYMENT_TYPES and no file is produced. The fault is in the bank profile, not in your payment, and setting paymentType does not help. When a connection is created for such a bank, BankConnector emits a connection.no-payment-rails event once (see Receiving results).