---
title: "Free structured payment reference check (JSON body)"
method: POST
path: "/v1/reference/validate"
tags: ["Free"]
---

# Free structured payment reference check (JSON body)

`POST /v1/reference/validate`

Same contract as the GET, with the reference in a JSON body — convenient for references carrying characters awkward to url-encode.

## Request body

- object
  - `reference` string, required
  - `reference_type` 'rf' | 'scor' | 'qrr' | 'ogm' | 'vcs' | 'viitenumero' | 'kid' | 'ocr'

## Response `200`

Reference verdict

- PaymentReferenceResult
  - `reference` string, required — Normalized: uppercase, separators removed
  - `scheme` 'rf' | 'qrr' | 'ogm' | 'viitenumero' | 'kid' | 'ocr', nullable, required — Null when no supported scheme matches the string
  - `valid` boolean, nullable, required — null is a REAL answer, not a missing one: the scheme was recognised and cannot be checked without the creditor bank configuration (KID, OCR). Never present null to a user as invalid.
  - `status` 'checked' | 'unverifiable_without_creditor_config' | 'unrecognised', required
  - `check_digit_expected` string — A STRING, so a two-digit value beginning with zero survives — an OGM remainder of 3 is "03", and a remainder of 0 is written "97".
  - `also_valid_as` object — The second reading of an ambiguous string, with its own verdict. A bare 12-digit reference is both a Belgian OGM and a legal Finnish length.
    - `scheme` string
    - `valid` boolean
    - `check_digit_expected` string
  - `source` string, nullable, required — The document that publishes the rule. Null only when no scheme matched, so no rule was applied. Relay it: it is what makes the verdict auditable.
  - `as_of` string — YYYY-MM of that document — the date it carries, never a future validity date
  - `note` string, required — What was checked, and what was not
  - `pairing_verdict` string — Pointer to POST /v1/iban/validate for the QRR/SCOR pairing verdict

## Other responses

- `400` — Missing reference, or malformed JSON body

---

[API](https://skmtc.dev/ibanforge/apis/ibanforge-api.md) · [All operations](https://skmtc.dev/ibanforge/apis/ibanforge-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ibanforge/ibanforge-api/revisions/9499dba434ea/schema)