IBANforge

Validate Payment Reference

validate_payment_reference

Read-onlyIdempotent

Validate payment references (RF, QRR, OGM, Finnish) and check compatibility with a Swiss IBAN, returning separate verdicts for reference validity and legal pairing.

Instructions

Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together. USE WHEN: assembling a payment instruction from an invoice, a QR-bill or a remittance advice; whenever a Swiss IBAN and a reference appear together; or when the user pastes an "RF..." string, a 27-digit number, or a +++123/4567/89012+++ block. DO NOT USE to validate the IBAN itself — that is validate_iban. SCHEMES: RF Creditor Reference (ISO 11649, "SCOR" in Swiss Payment Standards, mod 97-10); Swiss QR reference ("QRR", 27 digits, modulo 10 recursive); Belgian OGM/VCS (12 digits, modulo 97, a remainder of 0 written 97); Finnish viitenumero (4-20 digits, weights 7-3-1 from the right). Norwegian KID and Swedish OCR are RECOGNISED but never judged: they answer valid: null with status unverifiable_without_creditor_config, because modulus type and length are configured per creditor account by the beneficiary bank. NEVER relay those to a user as "invalid". AMBIGUITY: only a leading "RF" and a 27-digit length pin a scheme down. A bare 12-digit string is both a Belgian OGM and a legal Finnish length, so the more specific reading is returned and the other appears in also_valid_as. Pass reference_type when you know the country. THE PAIRING RULE: pass an iban and you also get a pairing verdict. Per the Swiss Implementation Guidelines a QRR reference may ONLY be used with a QR-IBAN (institution identifier in the SIX range 30000-31999), and an ISO 11649 reference may NOT be used with one. Outside CH and LI, pairing is not_applicable. valid and pairing are INDEPENDENT verdicts — a reference can be arithmetically valid and still illegal on that account. Relay source/as_of: they make the verdict auditable. COST: free without an iban (routed to GET /v1/reference/validate). WITH an iban it is routed to POST /v1/iban/validate and costs 0.005 USDC, which also returns the full IBAN enrichment — the pairing verdict is what that call buys.

Input Schema

TableJSON Schema

Name	Required	Description
`iban`	No	Optional creditor IBAN this reference would travel with. Supply it for the pairing verdict; that path is billed at 0.005 USDC.
`reference`	Yes	The reference as printed. Spaces, slashes and the Belgian +++...+++ wrapper are stripped. Examples: "RF18539007547034", "210000000003139471430009017", "+++010/8068/17183+++".
`reference_type`	No	Optional scheme hint, used when the string alone is ambiguous.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	Yes
`as_of`	No	YYYY-MM of that document.
`valid`	Yes	null means recognised but uncheckable without the creditor bank configuration (KID, OCR). Never report null as false.
`scheme`	Yes	Null when no supported scheme matches.
`source`	Yes	The document publishing the rule. Null only when no scheme matched. Relay it.
`status`	Yes
`pairing`	No	Present only when an iban was supplied.
`reference`	Yes	Normalized: uppercase, separators removed.
`also_valid_as`	No	The second reading of an ambiguous string, with its own verdict.
`pairing_as_of`	No
`pairing_source`	No	A DIFFERENT document from source.
`check_digit_expected`	No	A STRING, so a two-digit value beginning with zero survives ("03", "97").

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.8.0Sep 26, 2026

changedOutput schema / properties / scheme / enum

Previous value: -[
-  "rf",
-  "qrr",
-  "ogm",
-  "viitenumero",
-  "kid",
-  "ocr"
-]New value: +[
+  "rf",
+  "qrr",
+  "ogm",
+  "viitenumero",
+  "kid",
+  "ocr",
+  null
+]

changedOutput schema / properties / scheme / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

changedOutput schema / properties / source / description

Previous value: -"The document publishing the rule. Relay it."New value: +"The document publishing the rule. Null only when no scheme matched. Relay it."

changedOutput schema / properties / source / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

changedOutput schema / properties / valid / type

Previous value: -"boolean"New value: +[
+  "boolean",
+  "null"
+]

Addedv1.4.4Sep 2, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already show readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds meaningful behavior beyond those hints: the pairing-verdict independence ('valid and pairing are INDEPENDENT verdicts'), the paid POST route when iban is supplied, the cost in USDC, the ambiguity resolution mechanism, and explicit instruction to relay source/as_of for auditability. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense and earns its length: it covers schemes, ambiguity, pairing, cost, and unverifiable cases with clear topical markers. It is front-loaded with the primary purpose and USE WHEN/DO NOT USE guidance before lower-level scheme details. It could be slightly tightened, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description covers what would otherwise be gaps: scheme-domain knowledge, ambiguity handling, independence of valid and pairing verdicts, the unverifiable case instruction, and the cost-bearing POST route. For a tool with 3 parameters, complex scheme logic, and a paid path, the description is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value above that baseline by explaining the scheme ambiguity (e.g., a bare 12-digit string is both Belgian OGM and a legal Finnish length), clarifying the passthrough behavior of the reference normalization (spaces/slashes stripped), and explaining the iban parameter's pairing effect and cost implication. It adds interpretive meaning rather than restating the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pair ('Validate a structured payment reference') and immediately distinguishes the tool's scope from its sibling validate_iban by explicitly stating 'DO NOT USE to validate the IBAN itself — that is validate_iban.' It also enumerates the schemes and recognition modes, so an agent can tell exactly what is and is not this tool's job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('when assembling a payment instruction from an invoice, a QR-bill or a remittance advice; whenever a Swiss IBAN and a reference appear together') and when-not-to-use ('DO NOT USE to validate the IBAN itself') guidance, names the alternative tool, and gives a cost-based routing consideration. It also instructs not to relay 'unverifiable_without_creditor_config' verdicts as invalid, which is a critical usage rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server