Amounts

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.

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.

{
  "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.

{
  "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.

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.

{
  "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.

{
  "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.

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 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.

Getting Started

Program Configuration

Compliance

Accounts

Cards

Transactions

Spend Policies

Virtual Assets

Currencies

Amount shape by status

PENDING

CLEARED

VOID

DECLINED

Which field to display

Conversion rate

Per-event amounts

​Currencies

​Amount shape by status

​PENDING

​CLEARED

​VOID

​DECLINED

​Which field to display

​Conversion rate

​Per-event amounts

Currencies

Amount shape by status

PENDING

CLEARED

VOID

DECLINED

Which field to display

Conversion rate

Per-event amounts