Skip to content

Drive one simulated authorization against a named card

POST/v1/simulated-spends

Requires an API client bearer token.

Drives one simulated authorization against a card the operator issued and funded, over the same wire path a real network would use. The caller passes a card id, never a PAN — the PAN is resolved server-side against a single-use grant and never returned. NOT idempotency-keyed: each accepted call is a deliberately distinct wire transaction (press twice = two payments); the console disables the button while a request is in flight instead. Returns 202 with an acceptance handle plus the wire identity (stan/rrn, nullable). null does NOT mean nothing was sent — it covers both a leg refused before any message was built (safe to retry) and a leg whose outcome is genuinely unknown, e.g. a response that could not be read (NOT safe to assume nothing reached the wire — do not retry on this response alone; poll GET /v1/simulated-spends/{id} first). The decision itself is queryable via that same GET endpoint and arrives asynchronously as an authorization.decided event. A simulator-leg failure is recorded and reported there too, rather than surfacing as an error response here.

Request body

card_idstringrequired
amountobjectrequired
+ show properties
amountstringrequired
currency"EUR" | "GBP" | "USD"required
mccstringrequired
merchant_namestringrequired
channel"pos" | "ecommerce" | "atm" | "moto"required
entry_mode"contactless" | "chip" | "magstripe" | "manual"
scenario"partial_approval" | "force_stip_timeout" | "delegated_timeout" | "cvv2_presented" | "cavv_presented"
approved_amountobject
+ show properties
amountstringrequired

Non-negative canonical decimal, at most 16 integer digits. Fractional digits must not exceed the minor-unit precision of `currency` (2 for EUR/GBP/USD), because the amount has to be representable in ISO 8583 DE4.

currency"EUR" | "GBP" | "USD"required
cvv2string
auth_valuestring
threeds_refstring (uuid)
mitboolean
kind"purchase" | "refund"

Example

curl -X POST https://api.rigid.fi/v1/simulated-spends \
  -H "Authorization: Bearer $RIGID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "card_id": "string",
  "amount": {
    "amount": "string",
    "currency": "EUR"
  },
  "mcc": "string",
  "merchant_name": "string",
  "channel": "pos"
}'

Responses

202

The simulated spend was accepted for transmission.

simulation_idstringrequired
accepted_atstring (date-time)required
stanstring | nullrequired

The wire identity (DE11/DE37) this attempt was sent under. null does NOT mean "nothing was sent" — do not retry on that assumption. It covers two different causes this response cannot distinguish: (1) the leg was refused before a message was ever built (genuinely safe to retry), or (2) the outcome is unknown — a message may already be on the wire under an identity this response never learned. Poll GET /v1/simulated-spends/{id} instead of inferring anything from a null here: a row reaching failed WITH A NULL stan on THIS response is case 1 — a row that reached sent first (this stan non-null) and only then failed is NOT case 1, the message was already built and sent. A row still accepted after a safe interval is case 2 (or a lost bookkeeping write) — do not retry either way.

rrnstring | nullrequired

The wire identity (DE11/DE37) minted alongside stan under the same identity — always null/non-null together with it. See stan above: null does not by itself mean safe to retry.

network_txn_idstring
400

Validation error

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
401

Authentication required

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
403

Forbidden

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
404

Card not found

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
409

Card is not active

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring
500

Internal server error

typestringrequired
titlestringrequired
statusintegerrequired
detailstring
instancestring