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 REST calls/month, and POST /v1/keys/claim lifts that same key to 200 a month).

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.9/5.0

Behavior5/5

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

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: the independence of 'valid' and 'pairing', the fact that Norwegian KID and Swedish OCR are recognized but never judged (returning valid: null), the ambiguity resolution via 'also_valid_as', and the auditable source/as_of fields. It also discloses rate limits and key-generation costs, which no structured field conveys. No contradiction with annotations exists.

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

Conciseness5/5

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

The description is long but every section is purposeful and clearly labeled (USE WHEN, DO NOT USE, SCHEMES, AMBIGUITY, THE PAIRING RULE, IMPORTANT, FREE, COST). The most critical information is front-loaded in the opening sentence, and the cost/rate-limit details are actionable rather than fluff. The density is justified by the complexity of the domain.

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?

Given the tool's complexity—multiple reference schemes, pairing rules, ambiguity handling, and rate limits—the description is remarkably complete. It covers all accepted schemes, explains the NOT judged case for KID/OCR, clarifies the relationship between valid and pairing, and references the output fields (source/as_of) needed for auditability. The existence of an output schema means return-value detail need not be spelled out, and nothing needed for correct invocation 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?

The input schema already has 100% coverage with descriptive comments for all three parameters, giving a baseline of 3. The description adds meaningful decision guidance beyond the schema: 'Pass reference_type when you know the country' clarifies when the hint is needed, and the pairing-rule details specify what happens when an iban is supplied (QRR allowed only with QR-IBAN in the SIX range, ISO 11649 forbidden with one). This is useful but partially redundant with schema text, so a 4 is appropriate.

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 opening sentence names a specific verb and resource: 'Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together.' It goes beyond a generic label by stating the core function and the optional IBAN-pairing behavior, and it explicitly distinguishes itself from the sibling validate_iban with 'DO NOT USE to validate the IBAN itself — that is validate_iban.'

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?

The description provides an explicit 'USE WHEN' list covering concrete scenarios (assembling a payment instruction, Swiss IBAN + reference pairs, pasted RF/QRR/+++ blocks, correctness questions) and an explicit 'DO NOT USE' instruction naming the alternative tool. This leaves no ambiguity about when an agent should select this tool over its siblings.

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.