ibanforge

Validate Payment Reference

validate_payment_reference

Read-onlyIdempotent

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 (the pairing rule is what most integrations get wrong); or when the user pastes an "RF..." string, a 27-digit number, a +++123/4567/89012+++ block, or asks whether a payment reference is correct. 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 and are not a property of the string. NEVER relay those to a user as "invalid" — say the check needs the creditor bank configuration. 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 — the part no checksum library reproduces: 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 — there is no QR-IBAN to pair against — and that does not affect the reference's own checksum verdict. IMPORTANT: valid and pairing are INDEPENDENT. A reference can be arithmetically valid and still illegal on that account. Read both, and relay source/as_of — they are what makes the verdict auditable. FREE: the checksums are published commodities. The paid surface is POST /v1/iban/validate, which returns this same pairing block with the full IBAN enrichment. COST: $0 per call, on every surface (free with no key on this transport: 25 units a week per source address, one per call and one per IBAN in batch_validate_iban, reset on Monday 00:00 UTC. Or an ifk_ key with no e-mail at all: POST https://api.ibanforge.com/v1/keys/generate with no body for 25 calls/month, on the REST API or on this transport, and POST /v1/keys/claim lifts that same key to 200 a month. Send the key here as Authorization: Bearer ifk_… (or X-API-Key) and each call counts against it exactly as on the REST API).

Input Schema

TableJSON Schema

Name	Required	Description
`iban`	No	Optional creditor IBAN — supply it to get the pairing verdict
`reference`	Yes	The reference as printed; spaces, slashes and the +++…+++ wrapper are stripped
`reference_type`	No	Optional hint: rf \| scor \| qrr \| ogm \| vcs \| viitenumero \| kid \| ocr

Output Schema

TableJSON Schema

Name	Required	Description
`note`	Yes	What was checked, and what was not.
`as_of`	No	YYYY-MM of that document.
`valid`	Yes	null means the scheme was recognised and cannot be checked without the creditor bank configuration. Never report null as false.
`scheme`	Yes	rf \| qrr \| ogm \| viitenumero \| kid \| ocr, or null when nothing matched.
`source`	Yes	The document publishing the rule. Null only when no scheme matched. Relay it.
`status`	Yes	checked \| unverifiable_without_creditor_config \| unrecognised
`pairing`	No	Present only when an iban was supplied: ok \| qrr_requires_qr_iban \| scor_forbidden_with_qr_iban \| not_applicable
`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	The document publishing the pairing rule — a DIFFERENT one from source.
`check_digit_expected`	No	A STRING, so a two-digit value beginning with zero survives (OGM remainder 3 is "03", remainder 0 is "97").

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedSep 2, 2026

removedOutput schema / properties / scheme / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / scheme / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / source / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / source / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / valid / anyOf

Removed value: -[
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / valid / type
```
Added value: +[
+  "boolean",
+  "null"
+]
```

AddedAug 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare read-only/idempotent/non-destructive, but the description goes far beyond: scheme-by-scheme behaviour, the null/unverifiable_without_creditor_config outcome for KID/OCR, the warning never to relay those as invalid, the QRR/QR-IBAN pairing legality rule, and the independence of valid vs pairing. This is exactly the behavioural context an agent cannot get from structured fields.

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

Conciseness3/5

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

Front-loads purpose and is organised under clear headers (USE WHEN / DO NOT USE / SCHEMES / AMBIGUITY / PAIRING / COST), but it is very long. The COST block, including key-generation URLs and weekly/monthly quota mechanics, is disproportionately verbose for a tool definition.

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?

For a checksum tool with an output schema, the description covers everything an agent needs: supported schemes, ambiguity resolution, pairing semantics, the unverifiable case, and the auditability fields (source/as_of) referenced for relay. Nothing material is missing.

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 real meaning on top: iban triggers a pairing verdict (not just a field), and reference_type is explained as a disambiguator for the 12-digit OGM/Finnish collision, with `also_valid_as` as the fallback reading.

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?

States a specific verb+resource (validate a structured payment reference, plus the IBAN pairing decision) and explicitly scopes it against validate_iban. The scope is unambiguous and distinguishes it from every sibling.

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?

Explicit USE WHEN triggers (assembling a payment instruction, Swiss IBAN + reference, pasted 'RF...'/27-digit/+++ block) and an explicit DO NOT USE routing to validate_iban. Alternative-selection guidance is complete.

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

All ibanforge tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.