---
title: "Validate a scanner PIN and return merchant config"
method: POST
path: "/v1/scanner/session"
tags: ["Point of Sale"]
---

# Validate a scanner PIN and return merchant config

`POST /v1/scanner/session`

## Request

- Base URL: `https://api.insumermodel.com`
- URL: `https://api.insumermodel.com/v1/scanner/session`
- Auth: API key in header `X-API-Key`

Validate a scanner PIN and return the merchant config for a login-less branded scanner. Owner key only (the partner key that provisioned the merchant). Lets a scanner with no account of its own authenticate with just the merchant id + a PIN. Repeated failed PIN attempts are limited per merchant (429).

## Request body

- object
  - `merchantId` string, required
  - `pin` string, required: 4-8 digit PIN.

## Response `200`

PIN valid

- object
  - `ok` true
  - `data` object
    - `valid` true
    - `scannerId` string
    - `scannerName` string
    - `merchantName` string
    - `discountMode` 'highest' | 'stack' | 'capped'
    - `discountCap` integer
  - `meta` Meta
    - `version` string
    - `timestamp` string, date-time

## Other responses

- `400`: Missing merchantId or pin
- `401`: Invalid scanner code or PIN
- `403`: API key does not own this merchant
- `404`: Merchant not found
- `429`: Too many failed PIN attempts, or the key's daily request limit
- `500`: Unexpected server error. Safe to retry; no credits are charged on a 500. Router endpoints return the standard error envelope; standalone endpoints (the ones whose 200 is a flat object) return a flat {"error": "..."} object.

---

[API](https://skmtc.dev/insumermodel/apis/insumerapi.md) · [All operations](https://skmtc.dev/insumermodel/apis/insumerapi/llms.txt) · [OpenAPI document](https://skmtc.dev/insumermodel/apis/insumerapi/revisions/91f56fe9e3d8?raw)