> ## Documentation Index
> Fetch the complete documentation index at: https://developers.opencard.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction states

> Push card transaction lifecycle events to OpenCard — authorized, cleared, invoiced, and deleted states via the Issuer API.

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](/card-issuers/issuer-integration/cards).

**Response `202`** — accepted for asynchronous processing. Empty body on success.

***

## Example — cleared purchase

```json theme={null}
{
  "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.