PIN check — contactless | Switchbench Docs

Authorizations

apiKey

Request Body^required

Request body for the structured financial and PIN transaction routes (POST /transaction/{operation}/{channel}, POST /transaction/account-verification, and POST /transaction/pin/{check,change,unblock}/...). The operation and channel are carried by the route itself, not the body.

object

network

Target network. Only visa (the default when omitted) is supported; a mastercard request returns 501 Not Implemented. A request for a network whose product the organization is not entitled to (including an expired trial) returns 403 Forbidden.

string | null

default: visa

envelope

Common acceptance context shared by every structured transaction operation. Each field, when omitted, is filled from the tenant’s merchant/terminal/currency catalog.

object

currency

ISO 4217 alphabetic or numeric transaction currency (DE 49). Defaults to the resolved merchant’s currency.

string

merchant_id

Card acceptor identification code (DE 42). Defaults to the tenant’s configured merchant.

string

terminal_id

Card acceptor terminal identification (DE 41). Defaults to the resolved merchant’s terminal.

string

amount

Required for sale, refund, cash-withdrawal, reversal, void, and non-balance-inquiry advice; ignored for balance-inquiry, account-verification (both forced to amount 0), and the PIN operations.

object

amount

required

Transaction amount in minor units (DE 4).

integer format: int64

Example

fee

Transaction fee in minor units (DE 28).

integer format: int64

card

Card credential. Required by every route this body serves. card.pin carries the PIN to verify (pin-check) or the current PIN (pin-change, pin-unblock). SMP binds card as this one shape for every channel, including POS/contactless/magstripe and ATM — there is no channel-specific card variant with track2, emv_data, or an encrypted PIN block on the public API today; only pan, expiry, cvv2, cardholder_name, and pin reach SVE.

object

pan

required

Primary account number (DE 2).

string

Example

4111111111111111

expiry

required

Card expiry as MMYY (DE 14).

string

Example

cvv2

Card verification value 2.

string

cardholder_name

Cardholder name, for the card acceptor record.

string

pin

Clear PIN digits — never an encrypted PIN block. Only consumed by the pin-check/pin-change/pin-unblock routes, where it carries the PIN the cardholder is verifying or changing from; ignored by every other operation.

string

original_ref

Reference to a prior transaction, supplied on operations that act on an earlier message (reversal, advice, void; refund ignores it). Rendered into DE 90 / DE 37 / DE 38.

object

original_mti

Original message type indicator, e.g. 0100.

string

original_stan

Original system trace audit number (DE 11).

string

original_transmission_date_time

Original transmission date/time (DE 7), in MMDDhhmmss form.

string

original_rrn

Original retrieval reference number (DE 37).

string

original_auth_code

Original authorization identification response / approval code (DE 38).

string

type

Advice sub-type for the advice route (one of sale, cash-withdrawal, balance-inquiry, refund). Ignored for every other route.

string

new_pin

The new clear PIN digits. Required for POST /transaction/pin/change; ignored by every other route.

string

x-request-id

Trace correlation id for logging only. Prefer the X-Request-Id HTTP header.

string

Examples

Verify a cardholder PIN

{
  "card": {
    "pan": "4111111111111111",
    "expiry": "1229",
    "pin": "1234"
  }
}

200

The operation completed a full round trip. A declined transaction (DE 39 in parsed_response ≠ "00") is a valid business outcome and is still returned at 200.

Response body for the structured financial and PIN transaction routes on the success (200) path. A declined transaction (DE 39 ≠ "00") is still 200 — the outcome is in parsed_response, not surfaced as an HTTP error.

object

request_id

required

SMP-generated req_-prefixed correlation id for tracing and log correlation.

string

Example

req_abc123

sent

required

The outbound ISO 8583 message SVE built and SMP transmitted to the fintech backend, as uppercase hexadecimal.

string

parsed_request

required

A rendered view of a built ISO 8583 message: its MTI plus a set-field map keyed as "NN (Field Name)" (2 digits for DE ≤ 99, 3 digits above), ordered ascending by data-element number. Binary data elements are rendered as uppercase hex.

object

mti

required

Four-digit message type indicator, e.g. 0100.

string

Example

fields

required

Set data elements, keyed as "NN (Field Name)" and ordered ascending by data-element number.

object

key

additional properties

string

last_response_hex

Finalized ISO 8583 response message from the fintech backend, as uppercase hexadecimal.

string | null

parsed_response

One of:

object
null

A rendered view of a built ISO 8583 message: its MTI plus a set-field map keyed as "NN (Field Name)" (2 digits for DE ≤ 99, 3 digits above), ordered ascending by data-element number. Binary data elements are rendered as uppercase hex.

object

mti

required

Four-digit message type indicator, e.g. 0100.

string

Example

fields

required

Set data elements, keyed as "NN (Field Name)" and ordered ascending by data-element number.

object

key

additional properties

string

Examples

Approved operation

{
  "request_id": "req_abc123",
  "sent": "0200B23A80010000000000004111111111111111000000001000",
  "parsed_request": {
    "mti": "0200",
    "fields": {
      "02 (Primary Account Number)": "4111111111111111",
      "03 (Processing Code)": "000000",
      "04 (Amount, Transaction)": "000000001000"
    }
  },
  "last_response_hex": "0210B23A80010000000000004111111111111111000000001000C1B2C300",
  "parsed_response": {
    "mti": "0210",
    "fields": {
      "02 (Primary Account Number)": "4111111111111111",
      "38 (Authorization Identification Response)": "C1B2C3",
      "39 (Response Code)": "00"
    }
  }
}

400

Malformed request — the body is not valid JSON or does not match the schema, or card is missing or has an empty pan. Unsupported network values return 501, not 400. Engine-side input validation failures (for example a missing amount or PIN) currently surface as 502 engine errors.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Malformed structured transaction request",
  "status": 400,
  "detail": "The request must include a 'card' with a non-empty 'pan'."
}

401

Authentication failed — missing, malformed, invalid, revoked, or suspended API key, or a JWT bearer token was sent.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The supplied API key is missing, malformed, invalid, revoked, or suspended."
}

{
  "type": "about:blank",
  "title": "JWT authentication not supported",
  "status": 401,
  "detail": "This endpoint accepts CPS API keys only. JWT bearer support is pending CPS org-id resolution."
}

403

Product not entitled — the organization has no active trial or subscription for the product that serves the requested network. Checked after the 501 network check and again per frame at delivery.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "product_not_entitled",
  "title": "Product not entitled",
  "status": 403,
  "detail": "The organization is not entitled to the 'visa' product. Check the product entitlements in the dashboard."
}

429

Rate limit exceeded — either the API key’s configured requests-per-second limit, or the per-organization requests-per-second cap on a product trial (trial_rate_limited). A Retry-After header is returned.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "The API key has exceeded its configured requests-per-second limit."
}

{
  "type": "trial_rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "The organization's trial of the 'visa' product has exceeded its requests-per-second limit."
}

Headers

Retry-After

integer

Seconds to wait before retrying.

501

Unsupported network — only visa is supported today; a mastercard request (or any other value) fails here until SME structured support lands.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Unsupported network",
  "status": 501,
  "detail": "'mastercard' is not yet supported on the structured transaction routes. Only 'visa' is supported today; Mastercard/SME support is tracked as a follow-up issue."
}

502

Delivery error — no active mTLS connection for the org, or a write/read failure (a delivery timeout included) on the outbound leg to your fintech backend; also an engine HTTP error or an undecodable engine response. Engine-side input validation failures (for example a missing amount or PIN) also surface here as Engine error, not 400.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Delivery error",
  "status": 502,
  "detail": "No active mTLS connection for the org."
}

{
  "type": "about:blank",
  "title": "Engine error",
  "status": 502,
  "detail": "The network engine returned an HTTP error."
}

503

API-key validation with CPS is unavailable, so the tenant could not be resolved; or the product entitlement check at delivery could not be confirmed with CPS. Retry the request.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "API key validation unavailable",
  "status": 503,
  "detail": "SMP could not validate the supplied API key with CPS."
}

{
  "type": "entitlement_check_unavailable",
  "title": "Entitlement check unavailable",
  "status": 503,
  "detail": "SMP could not confirm product entitlement with CPS. Retry the request."
}

504

The Visa engine call itself timed out, hit an open circuit breaker, or failed at the transport level.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Engine timeout",
  "status": 504,
  "detail": "The network engine call timed out."
}

PIN check — contactless

Authorizations

Request Body required

Example

Example

Example

Examples

Responses

200

Example

Example

Example

Examples

400

Examples

401

Examples

403

Examples

429

Examples

Headers

501

Examples

502

Examples

503

Examples

504

Examples

Request Body^required