Transaction states

Transaction states are the primary channel for delivering purchases to OpenCard. Send every state in the lifecycle so connected EMS apps receive a complete and accurate history.

POST /api/v1/issuers/{slug}/cards/{card_id}/transaction_states
Scope: issuer-{slug}-transaction-states-write

{card_id} is the id you sent when creating the card. Response 202 — accepted for asynchronous processing. Empty body on success.

Example — cleared purchase

{
  "id": "tx_1234567891",
  "state": "cleared",
  "type": "CARD_PURCHASE",
  "invoice_number": null,
  "original_amount": 109.38,
  "original_currency": "SEK",
  "accounting_amount": 109.38,
  "accounting_currency": "SEK",
  "exchange_rate": 1.0,
  "vat_rate": 0.25,
  "vat_amount": 21.88,
  "vat_currency": "SEK",
  "purchase_merchant": "Coop Vasagatan",
  "purchase_time": "2025-11-17T15:35:11Z",
  "purchase_country": "SE",
  "purchase_city": "STOCKHOLM",
  "mcc_code": "5411",
  "merchant_number": "12345678",
  "terminal_id": "TERM001",
  "rrn": "123456789012",
  "auth_code": "A1B2C3"
}

Field reference

Field	Required	Description
`id`	✅	Your unique transaction id (same across states for one purchase)
`state`	✅	`authorized`, `cleared`, `invoiced`, or `deleted`
`type`	✅	`CARD_PURCHASE`, `CASH_WITHDRAWAL`, or `FEE_AND_DISCOUNT`
`invoice_number`	❌	Issuer invoice number when `state` is `invoiced`
`original_amount`	✅	Amount at point of purchase
`original_currency`	✅	ISO 4217 (3 letters)
`accounting_amount`	✅	Amount in cardholder billing currency
`accounting_currency`	✅	ISO 4217 (3 letters)
`exchange_rate`	✅	Rate between original and accounting amounts
`vat_rate`	❌	VAT rate at merchant
`vat_amount`	❌	VAT amount
`vat_currency`	❌	ISO 4217 for VAT
`purchase_merchant`	✅	Merchant name
`purchase_time`	✅	ISO 8601 UTC, e.g. `2025-11-17T15:35:11Z`
`purchase_country`	✅	ISO 3166-1 alpha-2
`purchase_city`	❌	City
`mcc_code`	✅	Merchant Category Code
`merchant_number`	✅	ISO 8583 field 42
`terminal_id`	✅	ISO 8583 field 41
`rrn`	✅	ISO 8583 field 37 (retrieval reference number)
`auth_code`	✅	ISO 8583 field 38

States

State	When to send
`authorized`	Once, when the purchase is authorized — see below
`cleared`	When the transaction settles
`invoiced`	When included on the cardholder’s issuer invoice (credit products only)
`deleted`	When an authorization is reversed before clearing

`authorized` — one event per purchase

Send one authorized state per purchase: the final authorization at the amount the cardholder approved. This is what EMS apps show the cardholder in real time. Do not send any of these as separate states:

Do not send	Why
`pre-authorized` / pre-auth holds	Hotel and fuel holds are not purchases. Wait for the actual authorization
Incremental authorizations	Amount top-ups on an open authorization — fold them into the final `authorized` or into `cleared`
Authorization adjustments / reversals of a partial amount	Send `cleared` with the final amount instead. Use `deleted` only when the whole authorization is reversed

If your systems produce several authorization messages for one purchase, collapse them to a single authorized state with the same transaction id, then continue the lifecycle with cleared. Use the same id for all states belonging to one purchase. EMS apps upsert on OpenCard’s internal id after ingestion — your id is the issuer reference across states.

Errors

HTTP	`error`	Meaning
`400`	`card_not_found`	No card registered for `{card_id}`
`409`	`duplicate_transaction_state`	Same `id` + `state` already received
`422`	`invalid_purchase_time`	`purchase_time` not valid ISO 8601
`422`	`card_missing_party`	Card missing buyer or seller party

What happens next

OpenCard normalizes the payload, links it to the card and TPA, and forwards events to EMS webhooks. Optional enrichment (receipts, true VAT, line items) may follow as separate webhook events at the EMS — you do not implement that layer as an issuer.

Issuer Integration

Digital receipts

API — Issuer

API — Receipts

Transaction states

Example — cleared purchase

Field reference

States

`authorized` — one event per purchase

Errors

What happens next

​Example — cleared purchase

​Field reference

​States

​authorized — one event per purchase

​Errors

​What happens next

Example — cleared purchase

Field reference

States

`authorized` — one event per purchase

Errors

What happens next