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

# Amounts

> Per-status amount fields, currency, and the conversion rate Reap applies.

The amount fields on a card transaction change shape based on `status`. A `PENDING` transaction tracks authorized vs reversed amounts because both can still move. A `CLEARED` transaction tracks cleared vs refunded amounts for the same reason. A `DECLINED` transaction is final and only records what was attempted.

This page describes the field shape per status and how the numbers evolve over the transaction's life. For the underlying scenarios (reversals, clearings, refunds) see [Lifecycle](/transactions/lifecycle).

## Currencies

Every transaction carries two currency fields.

| Field              | Description                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `currency`         | The cardholder's billing currency, in which the cardholder is ultimately charged. Fixed per card program (for example `USD` or `HKD`).                                   |
| `originalCurrency` | The currency the merchant charged in (ISO 4217). Equal to `currency` for same-currency transactions; otherwise the merchant's local currency (e.g. `EUR`, `JPY`, `HKD`). |

Same-currency transactions and cross-currency transactions use the same fields. When the two currencies are equal there is no FX involved and `conversionRate` is `1`.

## Amount shape by status

### PENDING

Pending transactions have not settled yet. The authorized amount can still grow (incremental authorization) or shrink (reversal), so both numbers are tracked alongside the current effective amount.

```json theme={null}
{
  "status": "PENDING",
  "currency": "USD",
  "originalCurrency": "EUR",
  "amount": {
    "authorized": 110.00,
    "reversed": 10.00,
    "current": 100.00
  },
  "originalAmount": {
    "authorized": 101.20,
    "reversed": 9.20,
    "current": 92.00
  },
  "conversionRate": 1.086957
}
```

| Field               | Meaning                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `amount.authorized` | Sum of all authorization events on the transaction, in `currency`.                                                |
| `amount.reversed`   | Sum of all reversal events.                                                                                       |
| `amount.current`    | Effective hold on the account: `max(0, authorized - reversed)`. This is the number to show as the pending amount. |
| `originalAmount.*`  | Same three values expressed in `originalCurrency`.                                                                |

### CLEARED

Cleared transactions have settled. They can still receive refunds, and refunds adjust the amount fields without changing the status.

```json theme={null}
{
  "status": "CLEARED",
  "currency": "USD",
  "originalCurrency": "USD",
  "amount": {
    "cleared": 100.00,
    "refunded": 25.00,
    "current": 75.00
  },
  "originalAmount": {
    "cleared": 100.00,
    "refunded": 25.00,
    "current": 75.00
  },
  "conversionRate": 1.0
}
```

| Field              | Meaning                                             |
| ------------------ | --------------------------------------------------- |
| `amount.cleared`   | Sum of all clearing events on the transaction.      |
| `amount.refunded`  | Sum of all refund events.                           |
| `amount.current`   | Effective net charge: `max(0, cleared - refunded)`. |
| `originalAmount.*` | Same three values expressed in `originalCurrency`.  |

A full refund leaves `amount.current` at `0` while the status remains `CLEARED`. See [Refund on a cleared transaction](/transactions/lifecycle#refund-on-a-cleared-transaction-related-refund).

### VOID

Void transactions are either authorizations that were fully reversed before clearing, or zero-amount card validity checks. The shape mirrors `PENDING` but `current` is `0`.

```json theme={null}
{
  "status": "VOID",
  "currency": "USD",
  "originalCurrency": "USD",
  "amount": {
    "authorized": 250.00,
    "reversed": 250.00,
    "current": 0.00
  },
  "originalAmount": {
    "authorized": 250.00,
    "reversed": 250.00,
    "current": 0.00
  }
}
```

`VOID` transactions do not carry a `conversionRate`.

### DECLINED

Declined transactions were rejected at authorization. No funds were ever held, so the response only records the attempted amount and the reason.

```json theme={null}
{
  "status": "DECLINED",
  "currency": "USD",
  "originalCurrency": "EUR",
  "originalAmount": 50.00,
  "declineReason": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for this transaction."
  }
}
```

| Field            | Meaning                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------- |
| `originalAmount` | Flat number. The amount the merchant attempted to charge, in `originalCurrency`.        |
| `declineReason`  | Why the transaction was declined. See [Decline reasons](/transactions/decline-reasons). |

There is no `amount` field on a declined transaction, because nothing was charged in `currency`. There is no `conversionRate` either, because no conversion took place.

## Which field to display

`amount.current` is the single field most product surfaces want to render. It always reflects the latest effective amount on the transaction, recomputed every time a new event arrives. The [lifecycle scenarios](/transactions/lifecycle#scenarios) describe what changes it under each event type.

If you need a step-by-step view, the `events` array carries the precise amount and timestamp of every authorization, clearing, reversal, and refund.

## Conversion rate

`conversionRate` is the rate Reap applied to convert `originalAmount` into `amount`, expressed as the multiplier such that `amount ≈ originalAmount * conversionRate`. It is rounded to 6 decimal places.

* `1.0` whenever `currency` and `originalCurrency` are the same.
* Otherwise, the effective `currency`-per-`originalCurrency` rate, as of authorization time.

`conversionRate` is present on `PENDING` and `CLEARED`, and absent on `VOID` and `DECLINED`.

## Per-event amounts

The `events` array on every transaction (except `DECLINED`, which has a single decline event) uses the same currency model as the parent transaction. Each event carries:

| Field              | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `type`             | One of `AUTHORIZATION`, `CLEARING`, `REVERSAL`, `REFUND`, `DECLINE`. |
| `amount`           | Event amount in `currency`.                                          |
| `originalAmount`   | Event amount in the event's `originalCurrency`.                      |
| `originalCurrency` | The currency the event was reported in.                              |
| `occurredAt`       | When the event happened on the card network.                         |

The transaction-level breakdowns above are simply aggregates over `events`. If you need an audit trail of exactly what was authorized, reversed, cleared, or refunded and when, read the `events` array directly.