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

# Cardholder fees

> The FX and ATM fees charged to cardholders, how to set them for your program, and how to override them for a single account.

Cardholder fees are charged to the cardholder on top of the merchant amount when a card transaction is authorized, so the amount debited from the account is higher than the amount the merchant asked for. Every program carries a default rate for each fee type. You can change those defaults and override any of them for a single account.

## Fee types

| Type                        | Charged when                                                        | Unit                                  |
| --------------------------- | ------------------------------------------------------------------- | ------------------------------------- |
| `FX_MARKUP`                 | The merchant charges in a currency other than your billing currency | Basis points of the bill amount       |
| `ATM_DOMESTIC_VARIABLE`     | A domestic ATM withdrawal                                           | Basis points of the bill amount       |
| `ATM_DOMESTIC_FIXED`        | A domestic ATM withdrawal                                           | Fixed amount in your billing currency |
| `ATM_CROSS_BORDER_VARIABLE` | A cross-border ATM withdrawal                                       | Basis points of the bill amount       |
| `ATM_CROSS_BORDER_FIXED`    | A cross-border ATM withdrawal                                       | Fixed amount in your billing currency |

100 basis points is 1%. A rate of `0` or an amount of `0` turns a fee off without deleting it.

An ATM withdrawal is **domestic** when the ATM is in the same country as your card program, and **cross-border** otherwise. A cross-currency ATM withdrawal pays the FX markup as well as the ATM pair for its tier.

The fixed ATM fee is charged once per withdrawal.

## Defaults and overrides

Each fee has a **scope**:

* `PROJECT`: the default for your whole program. Every project has exactly one row per fee type. You can change its value but you cannot create or delete it. The project is the one you authenticate as, so this scope carries no `id`.
* `ACCOUNT`: an override for one account. It replaces the project default for that fee type on every card of that account. An account can have at most one override per fee type.

When Reap prices a transaction it uses the account override where one exists and the project default otherwise. Each transaction records the fee row that priced it and the version that row was on. Changing a fee later never rewrites the history of settled transactions.

<Warning>
  Set your program's default fees in the dashboard before you launch in production. Only an organization Admin can change project defaults, and only from the dashboard; an API key cannot update them. Account overrides can be managed from the dashboard or the API.
</Warning>

## Set an override

Create an override for one fee type on one account. The `value` says how the fee is denominated: `unit: "BPS"` with a `bps` rate for a rate-based type, `unit: "AMOUNT"` with an `amount` for a fixed one.

```bash theme={null}
curl -X POST https://api.reap.global/fees \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ATM_DOMESTIC_FIXED",
    "scope": { "type": "ACCOUNT", "id": "1c4e0c5e-9b6b-4d5a-8e2e-3f1b2c7a9d10" },
    "value": { "unit": "AMOUNT", "amount": 1.5 }
  }'
```

```json theme={null}
{
  "id": "6f0b3c6e-6d2f-4f0e-9c1e-1d2f3a4b5c6d",
  "type": "ATM_DOMESTIC_FIXED",
  "value": { "unit": "AMOUNT", "amount": 1.5, "currency": "USD" },
  "scope": { "type": "ACCOUNT", "id": "1c4e0c5e-9b6b-4d5a-8e2e-3f1b2c7a9d10" },
  "version": 1,
  "createdAt": "2026-09-11T09:12:44.000Z",
  "updatedAt": "2026-09-11T09:12:44.000Z"
}
```

A fixed fee is always denominated in your program's billing currency, which the response reports as `currency`. A rate-based value carries no currency: it applies to the bill amount whatever that currency is.

Update a fee with [Update fee value](/api-reference/fees/update-fee-value); the `version` increments on every change. Delete an override with [Delete fee override](/api-reference/fees/delete-fee-override) and the account falls back to the project default. Creating a second override for the same type and account returns `409 DUPLICATE_FEE`.

## Read what an account pays

[List effective fees](/api-reference/fees/list-effective-fees) returns one entry per fee type for an account, each naming the row that supplies it.

```bash theme={null}
curl "https://api.reap.global/fees/effective?accountId=1c4e0c5e-9b6b-4d5a-8e2e-3f1b2c7a9d10" \
  -H "Authorization: Bearer $API_KEY"
```

```json theme={null}
{
  "items": [
    {
      "type": "FX_MARKUP",
      "value": { "unit": "BPS", "bps": 150 },
      "source": {
        "feeId": "0b1f6a2e-4a3c-4d8e-9f10-2a3b4c5d6e7f",
        "scope": { "type": "PROJECT" }
      }
    },
    {
      "type": "ATM_DOMESTIC_FIXED",
      "value": { "unit": "AMOUNT", "amount": 1.5, "currency": "USD" },
      "source": {
        "feeId": "6f0b3c6e-6d2f-4f0e-9c1e-1d2f3a4b5c6d",
        "scope": { "type": "ACCOUNT", "id": "1c4e0c5e-9b6b-4d5a-8e2e-3f1b2c7a9d10" }
      }
    }
  ]
}
```

[List fees](/api-reference/fees/list-fees) returns the rows themselves, filtered by `type`, `scopeType`, or `scopeId`.

## What appears on the transaction

Each transaction reports the fees it charged under `fees`: `fx` for the FX markup and `atm` for the ATM pair combined, both in your billing currency. See [Amounts](/transactions/amounts) for how these aggregate across authorization, clearing, and refund events.