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

# Read card transactions

> List card-payment lifecycles and interpret billing amounts, merchant amounts, and statuses.

Use the card-transactions resource to build a user's card activity history. Each item represents one card-payment lifecycle, not one card-network event. The same item changes as an authorization clears, reverses, is cancelled, or is declined.

> [!NOTE]
>
> The Partner API exposes card transactions separately from deposits and withdrawals. See [Manage money movements](https://docs.gnosispay.com/platform-integration/manage-accounts/deposit-withdrawal.md) to build a combined account activity view.

## List transactions for an account

Call [`GET /card-transactions`](https://docs.gnosispay.com/api-reference/partner-api/card-transactions/list-card-transactions) with the required `account_id` query parameter. Results are ordered newest first.

```bash cURL theme={null}
curl --request GET \
  --url "https://core.sandbox.gnosispay.in/partner-api/v1/card-transactions?account_id=ACCOUNT_ID&page_size=20" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

You can restrict the results by lifecycle creation time with `created_at_start` and `created_at_end`. Send both values as RFC 3339 timestamps.

```bash cURL theme={null}
curl --request GET \
  --url "https://core.sandbox.gnosispay.in/partner-api/v1/card-transactions?account_id=ACCOUNT_ID&created_at_start=2026-11-01T00%3A00%3A00Z&created_at_end=2026-12-01T00%3A00%3A00Z&page_size=20" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

While `pagination.has_next` is `true`, pass `pagination.next_page_cursor` as `page_cursor` in the next request. A cursor belongs to this endpoint and filter set; don't reuse it for deposits, withdrawals, or different filters.

## Read the latest lifecycle state

Store each transaction's `id`. Call [`GET /card-transactions/{card_transaction_id}`](https://docs.gnosispay.com/api-reference/partner-api/card-transactions/get-a-card-transaction) when you need its latest status and amounts.

The public statuses are:

| Status | Meaning |
| - | - |
| `authorized` | Funds are reserved against the account. |
| `cleared` | The transaction is posted against the account. |
| `reversed` | Previously reserved or posted funds are returned. |
| `cancelled` | The authorization is cancelled before posting. |
| `declined` | The authorization attempt is declined. |
| `unknown` | The lifecycle cannot yet be classified. Read it again later. |

> [!WARNING]
>
> Don't treat the first response as final. Use `updated_at` and the current `status`; the amount can also change when clearing data arrives.

## Interpret transaction amounts

Every transaction contains a required billing amount and may contain a merchant amount:

```json theme={null}
{
  "direction": "debit",
  "amounts": {
    "billing": {
      "amount": "1230",
      "currency": "EUR",
      "decimals": 2
    },
    "merchant": {
      "amount": "1350",
      "currency": "USD",
      "decimals": 2
    }
  }
}
```

| Field | Meaning |
| - | - |
| `amounts.billing` | The current amount reserved or posted against the account, in the account's billing currency. It uses the cleared total when available and otherwise the authorized total. |
| `amounts.merchant` | The current amount in the merchant or acquirer's currency. It follows the same cleared-then-authorized rule and is `null` when the card network did not supply merchant-currency data. |

Amounts are base-10 integer strings in the currency's smallest unit. Use `decimals` to display them: `"1230"` with `2` decimals is `12.30`. Use a decimal or big-integer library, never floating-point arithmetic.

> [!WARNING]
>
> Don't substitute `amounts.billing` when `amounts.merchant` is `null`. They answer different questions and can use different currencies.

`direction` describes the account effect: `debit` removes money and `credit` returns money.

## Display merchant and decline details

The `merchant` object contains card-network data when available: `name`, `city`, `country`, and `category_code`. The entire object or any field can be `null`, so design a fallback display using `description` without assuming a merchant name exists.

`decline_reason` is present only when `status` is `declined`. See [Card decline reasons](https://docs.gnosispay.com/concepts/card/decline-codes.md) for guidance on user-facing messages.

## Check ownership

Your partner token can read transactions for every account in your organization. Before listing or displaying transactions, check that the `account_id` belongs to the user making the request. Apply the same check when a user opens a transaction by `card_transaction_id`.

## Next step

> [card] [Build account activity](https://docs.gnosispay.com/platform-integration/manage-accounts/deposit-withdrawal.md)
>
> Combine card transactions, deposits, and withdrawals in your application.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.