Validate Payment Reference
validate_payment_referenceValidate a structured payment reference and, when an IBAN is supplied, confirm whether they can legally travel together. Supports RF, Swiss QR, OGM, and more.
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
| Name | Required | Description | Default |
|---|---|---|---|
| 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
| Name | Required | Description | Default |
|---|---|---|---|
| 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. 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"). |