> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Fees
> Configure fees on card transactions to generate additional revenue
This page is part of the legacy Bridge Cards API. For new integrations, use the [consumer issuing guide](/platform/cards/overview/stripe-issuing) instead.
## **Overview**
Bridge allows you to configure fees on card transactions, enabling you to generate additional revenue beyond interchange share. These fees are automatically calculated and deducted from your customers' wallets at the time of each card transaction.
There are two types of fees you can configure:
| **Fee Type** | **Description** | **When Applied** |
| :-------------- | :-------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| Transaction Fee | A percentage-based fee, fixed fee, or both applied to the transaction amount | All transactions, configurable for domestic and/or international |
| FX Fee | A percentage-based premium on the exchange rate for foreign currency transactions | Transactions where currency conversion occurs |
Fees are included in the terms accepted by end users when they sign up for a card. The fee amounts are disclosed to customers as part of the card program terms.
## **Fee Types**
### Transaction Fees
Transaction fees are surcharges applied to the transaction amount. You can configure transaction fees as:
* **Percentage-based only**: A percentage of the transaction amount (e.g., 1%)
* **Fixed amount only**: A flat fee per transaction (e.g., `$0.30`)
* **Both percentage and fixed**: A combination of percentage plus fixed amount (e.g., 1% + `$0.30`)
Fixed fees are charged once per transaction, regardless of how many authorizations occur. For example, if a transaction has an incremental authorization (where the merchant increases the amount after the initial auth), the fixed fee is only applied once on the initial authorization—not on each subsequent incremental auth.
You can configure different fee rates for:
* **International transactions**: Transactions where the merchant is located outside the card's country of issuance
* **Domestic transactions**: Transactions where the merchant is in the same country as the card's country of issuance
### FX Fees
FX fees are percentage-based premiums applied to the exchange rate provided by the card network whenever currency conversion occurs. When a cardholder makes a purchase in a currency different from their card's currency (e.g., a USD cardholder purchasing in EUR, GBP, or JPY), the transaction is converted using the network's exchange rate plus your configured FX fee percentage.
For example, if the network's exchange rate is 1.10 USD/EUR and you have a 1.5% FX fee configured, the effective exchange rate applied to the transaction would be approximately 1.0835 USD/EUR.
## **Configuring Fees**
Fee configurations are set up during your onboarding process with Bridge. To configure or modify your fee structure:
1. Contact the Bridge team to discuss your desired fee configuration
2. Specify your fee rates for each applicable fee type
3. Bridge will configure your fee settings
Fee configurations apply globally across all card accounts for your integration. Per-customer fee customization is not currently supported. Changes to fee configurations require Bridge approval and should be infrequent.
### Configuration Options
| **Setting** | **Description** | **Example** |
| :----------------------------------------- | :-------------------------------------------- | :----------------------- |
| International transaction fee (percentage) | Percentage fee for international transactions | 1.00% (100 basis points) |
| International transaction fee (fixed) | Fixed amount for international transactions | `$0.30` |
| Domestic transaction fee (percentage) | Percentage fee for domestic transactions | 0.50% (50 basis points) |
| Domestic transaction fee (fixed) | Fixed amount for domestic transactions | `$0.25` |
| FX premium | Percentage fee applied to the exchange rate | 1.50% (150 basis points) |
You can configure percentage fees, fixed fees, or both for each transaction type. For example, you might set international transactions to `1% + $0.30`, while domestic transactions have only a `$0.25` fixed fee.
## **How Fees Are Applied**
When a card transaction is authorized, Bridge calculates the applicable fees and includes them in the total amount debited from the cardholder's wallet. The fee calculation happens as follows:
1. The card network sends the transaction authorization request with the transaction amount
2. Bridge determines if the transaction is domestic or international
3. If applicable, Bridge applies the transaction fee percentage and any fixed fee
4. For transactions where currency conversion occurs, Bridge applies the FX premium to the exchange rate
5. The total amount (transaction amount + fees) is debited from the cardholder's wallet
Fees are typically applied at the time of authorization. This means the fee amount is included in the hold placed on the cardholder's balance when the transaction is first approved.
## **Fees in Webhooks**
Fee information is included in `card_transaction` webhook events. The `fees` object provides a complete breakdown of all fees applied to a transaction.
### Fee Object Structure
The fee information is included at the top level of the transaction webhook payload:
```json expandable theme={null}
{
"id": "b3f589e1-f66b-5cf7-c24b-4c9addb593b",
"fees": {
"transaction_fee": {
"fee_amount": "-0.5",
"fee_config": {
"fixed_fee_amount": "0.5"
},
"is_international": false
},
"total_fee_amount": "-0.5"
},
"amount": "-0.99",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-12-17T15:48:30.490Z",
"updated_at": "2025-12-17T15:50:18.547Z",
"customer_id": "2e4ab8ed-58b5-552g-ac08-67771c25e072",
"authorized_at": "2025-12-17T15:48:30.497Z",
"merchant_name": "ECOMMERCE STORE",
"status_reason": "approved",
"billing_amount": "-0.99",
"card_account_id": "d742b7g5-61be-5b33-bd75-45c9bbe4c2ea",
"original_amount": "-0.99",
"merchant_location": "SAN JOSE, CA",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.5",
"fee_config": {
"fixed_fee_amount": "0.5"
},
"is_international": false
},
"total_fee_amount": "-0.5"
},
"amount": "-0.99",
"wallet": "other",
"account": {
"last_4": "4821"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "CA",
"country": "USA",
"category": "department_stores",
"description": "ECOMMERCE STORE SAN JOSE CA",
"postal_code": "951260000",
"category_code": "5311"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-12-17T15:48:30.000Z",
"customer_id": "2e4ab8ed-58b5-552g-ac08-67771c25e072",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-0.99",
"transaction_id": "b3f589e1-f66b-5cf7-c24b-4c9addb593b",
"approval_status": "approved",
"card_account_id": "d742b7g5-61be-5b33-bd75-45c9bbe4c2ea",
"cashback_amount": "0.00",
"authorization_id": "g13d8g27-814f-6494-95c9-f6a32ca16g22",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "mismatch",
"address_postal_code_check": "mismatch"
},
"local_transaction_details": {
"amount": "-0.99",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5311",
"transaction_description": "ECOMMERCE STORE SAN JOSE CA"
}
```
### Fee Fields Reference
| **Field** | **Description** |
| :------------------------------------------------------------ | :------------------------------------------------------------------------------ |
| `fees.total_fee_amount` | The total fee amount deducted from the cardholder's wallet for this transaction |
| `fees.fx_fee.fee_amount` | The fee amount attributable to the FX premium |
| `fees.fx_fee.local_currency` | The original currency of the transaction at the merchant |
| `fees.fx_fee.is_international` | Whether the transaction was classified as international |
| `fees.fx_fee.original_exchange_rate` | The exchange rate provided by the card network before the FX premium |
| `fees.fx_fee.effective_exchange_rate` | The exchange rate applied after adding the FX premium |
| `fees.fx_fee.fee_config.percentage_fee_basis_points` | Your configured FX fee rate in basis points |
| `fees.transaction_fee.fee_amount` | The fee amount from the transaction fee |
| `fees.transaction_fee.is_international` | Whether the transaction was classified as international |
| `fees.transaction_fee.fee_config.percentage_fee_basis_points` | Your configured transaction fee rate in basis points |
| `fees.transaction_fee.fee_config.fixed_fee_amount` | Your configured fixed fee amount per transaction |
### Webhook Scenarios with Fees
Below are examples of card transaction webhooks showing how fees appear in different scenarios.
#### Successful Transaction with Fees
A successful transaction can go through multiple stages: initial authorization, preauth completion, and settlement. The fee is charged at the initial authorization and persists through the transaction lifecycle.
In these examples, the fee is calculated as: 1% of `$1.11` (`$0.01`) + `$0.10` fixed fee = `$0.11`.
When a card transaction is first approved, the fee is calculated and included:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_t6svpKfUvYmRxQRBL7wMvsg",
"event_developer_id": "6cd7ec7c-6857-45d9-9eff-607577a5f382",
"event_sequence": 22100,
"event_category": "card_transaction",
"event_type": "card_transaction.created",
"event_object_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"event_object_status": "approved",
"event_object": {
"id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"fees": {
"transaction_fee": {
"fee_amount": "-0.11",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.11"
},
"amount": "-1.11",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-09T15:01:58.478Z",
"updated_at": "2025-10-09T15:02:01.638Z",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"authorized_at": "2025-10-09T15:01:58.497Z",
"merchant_name": "ECOMMERCE.COM",
"status_reason": "approved",
"billing_amount": "-1.11",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"original_amount": "-1.11",
"merchant_location": "+14155557142, WAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.11",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.11"
},
"amount": "-1.11",
"wallet": "other",
"account": {
"last_4": "3111"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-09T15:01:58.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-1.11",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-1.11",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5734",
"transaction_description": "ECOMMERCE.COM +14155557142 WAUS"
},
"event_object_changes": {},
"event_created_at": "2025-10-09T15:02:02.791Z"
}
```
At preauth completion, the `authorization_infos` array contains both the preauth\_completion and original auth. The top-level `fees` shows the total fee, while each authorization shows its individual fee (the preauth\_completion shows `0.0` since the fee was already charged on the initial auth):
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_t2mA7ae7KNJy232Y1kADhLR",
"event_developer_id": "6cd7ec7c-6857-45d9-9eff-607577a5f382",
"event_sequence": 22164,
"event_category": "card_transaction",
"event_type": "card_transaction.updated",
"event_object_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"event_object_status": "approved",
"event_object": {
"id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"fees": {
"transaction_fee": {
"fee_amount": "-0.11",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.11"
},
"amount": "-1.11",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-09T15:01:58.478Z",
"updated_at": "2025-10-10T00:18:10.345Z",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"authorized_at": "2025-10-09T15:01:58.497Z",
"merchant_name": "ECOMMERCE.COM",
"status_reason": "approved",
"billing_amount": "-1.11",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"original_amount": "-1.11",
"merchant_location": "+14155137142, WAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "0.0",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "0.0"
},
"amount": "-1.11",
"wallet": "other",
"account": {
"last_4": "3111"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "preauth_completion",
"recurring": false,
"created_at": "2025-10-10T00:18:05.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": true,
"status_reason": "approved",
"billing_amount": "-1.11",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "b31da99c-6013-5e35-974c-eb75705c680e",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-1.11",
"currency": "usd",
"exchange_rate": "1.0"
},
"original_authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.11",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.11"
},
"amount": "-1.11",
"wallet": "other",
"account": {
"last_4": "6360"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-09T15:01:58.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-1.11",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-1.11",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5734",
"transaction_description": "ECOMMERCE.COM +14155557142 WAUS"
},
"event_object_changes": {
"updated_at": [
...
],
"authorization_infos": [
...
]
},
"event_created_at": "2025-10-10T00:18:10.954Z"
}
```
When the transaction settles, the fee information persists unchanged:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_tgX252cKCHQcBHhwf7XjTZd",
"event_developer_id": "6cd7ec7c-6857-45d9-9eff-607577a5f382",
"event_sequence": 22178,
"event_category": "card_transaction",
"event_type": "card_transaction.updated.status_transitioned",
"event_object_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"event_object_status": "settled",
"event_object": {
"id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"fees": {
"transaction_fee": {
"fee_amount": "-0.11",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.11"
},
"amount": "-1.11",
"status": "settled",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-09T15:01:58.478Z",
"updated_at": "2025-10-10T17:08:18.750Z",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"authorized_at": "2025-10-09T15:01:58.497Z",
"merchant_name": "ECOMMERCE.COM",
"status_reason": "approved",
"billing_amount": "-1.11",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"original_amount": "-1.11",
"merchant_location": "+14155557142, WAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "0.0",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "0.0"
},
"amount": "-1.11",
"wallet": "other",
"account": {
"last_4": "3111"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "preauth_completion",
"recurring": false,
"created_at": "2025-10-10T00:18:05.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": true,
"status_reason": "approved",
"billing_amount": "-1.11",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "b31da99c-6013-5e35-974c-eb75705c680e",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-1.11",
"currency": "usd",
"exchange_rate": "1.0"
},
"original_authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.11",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.11"
},
"amount": "-1.11",
"wallet": "other",
"account": {
"last_4": "6360"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-09T15:01:58.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-1.11",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-1.11",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5734",
"transaction_description": "ECOMMERCE.COM +14155557142 WAUS"
},
"event_object_changes": {
"status": [
"approved",
"settled"
],
"updated_at": ...
},
"event_created_at": "2025-10-10T17:08:20.362Z"
}
```
##### Over Capture and Under Capture
The preauth completion amount can differ from the original authorization amount. This happens when merchants capture more (over capture) or less (under capture) than the initially authorized amount. When this occurs, the fee adjusts based on the final captured amount.
When a merchant captures more than the original authorization (e.g., original auth was `$10.00` but final capture is `$12.00`), an additional fee is charged for the difference. The top-level `fees` reflects the updated total fee based on the captured amount:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_t2mA7ae7KNJy232Y1kADhLR",
"event_developer_id": "6cd7ec7c-6857-45d9-9eff-607577a5f382",
"event_sequence": 22164,
"event_category": "card_transaction",
"event_type": "card_transaction.updated",
"event_object_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"event_object_status": "approved",
"event_object": {
"id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"fees": {
"transaction_fee": {
"fee_amount": "-0.22",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.22"
},
"amount": "-12.00",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-09T15:01:58.478Z",
"updated_at": "2025-10-10T00:18:10.345Z",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"authorized_at": "2025-10-09T15:01:58.497Z",
"merchant_name": "ECOMMERCE.COM",
"status_reason": "approved",
"billing_amount": "-12.00",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"original_amount": "-10.00",
"merchant_location": "+14155137142, WAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.02",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.02"
},
"amount": "-12.00",
"wallet": "other",
"account": {
"last_4": "3111"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "preauth_completion",
"recurring": false,
"created_at": "2025-10-10T00:18:05.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-12.00",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "b31da99c-6013-5e35-974c-eb75705c680e",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-12.00",
"currency": "usd",
"exchange_rate": "1.0"
},
"original_authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.20",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.20"
},
"amount": "-10.00",
"wallet": "other",
"account": {
"last_4": "6360"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-09T15:01:58.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-10.00",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-10.00",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5734",
"transaction_description": "ECOMMERCE.COM +14155557142 WAUS"
},
"event_object_changes": {
"amount": ["-10.00", "-12.00"],
"updated_at": [...],
"authorization_infos": [...]
},
"event_created_at": "2025-10-10T00:18:10.954Z"
}
```
In this example, the original auth was `$10.00` with a fee of `$0.20` (1% of `$10` + `$0.10` fixed). The over capture of `$12.00` adds an additional percentage fee of `$0.02` (1% of the extra `$2.00`), bringing the total fee to `$0.22`. The fixed fee is not charged again.
When a merchant captures less than the original authorization (e.g., original auth was `$10.00` but final capture is `$8.00`), a portion of the percentage fee is refunded. The fixed fee is not refunded:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_t2mA7ae7KNJy232Y1kADhLR",
"event_developer_id": "6cd7ec7c-6857-45d9-9eff-607577a5f382",
"event_sequence": 22164,
"event_category": "card_transaction",
"event_type": "card_transaction.updated",
"event_object_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"event_object_status": "approved",
"event_object": {
"id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"fees": {
"transaction_fee": {
"fee_amount": "-0.18",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.18"
},
"amount": "-8.00",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-09T15:01:58.478Z",
"updated_at": "2025-10-10T00:18:10.345Z",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"authorized_at": "2025-10-09T15:01:58.497Z",
"merchant_name": "ECOMMERCE.COM",
"status_reason": "approved",
"billing_amount": "-8.00",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"original_amount": "-10.00",
"merchant_location": "+14155137142, WAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "0.02",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "0.02"
},
"amount": "-8.00",
"wallet": "other",
"account": {
"last_4": "3111"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "preauth_completion",
"recurring": false,
"created_at": "2025-10-10T00:18:05.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-8.00",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "b31da99c-6013-5e35-974c-eb75705c680e",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-8.00",
"currency": "usd",
"exchange_rate": "1.0"
},
"original_authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.20",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.20"
},
"amount": "-10.00",
"wallet": "other",
"account": {
"last_4": "6360"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "WA",
"country": "USA",
"category": "computer_software_stores",
"description": "ECOMMERCE.COM +14155557142 WAUS",
"postal_code": "98117",
"category_code": "5734"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-09T15:01:58.000Z",
"fee_amount": "0.00",
"customer_id": "af6071ae-2e83-45ed-8f01-2174db6a617e",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-10.00",
"transaction_id": "0ad0f797-9805-4c3a-8fa0-c77a1be52e4b",
"approval_status": "approved",
"card_account_id": "9ae899d5-fef2-488a-8321-e6447f52196d",
"cashback_amount": "0.00",
"authorization_id": "d9d534a0-87d8-506d-a0bb-12725ffc4599",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-10.00",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5734",
"transaction_description": "ECOMMERCE.COM +14155557142 WAUS"
},
"event_object_changes": {
"amount": ["-10.00", "-8.00"],
"updated_at": [...],
"authorization_infos": [...]
},
"event_created_at": "2025-10-10T00:18:10.954Z"
}
```
In this example, the original auth was `$10.00` with a fee of `$0.20` (1% of `$10` + `$0.10` fixed). The under capture of `$8.00` refunds `$0.02` of the percentage fee (1% of the `$2.00` difference), bringing the total fee to `$0.18`. The fixed fee (`$0.10`) is not refunded.
#### Incremental Authorization with Fees
When a transaction has an incremental authorization (e.g., adding a tip at a restaurant), the fixed fee is only charged once on the initial authorization. Subsequent incremental authorizations only apply the percentage fee to the additional amount.
In the initial auth, the fee is calculated as: 1% of `$7.34` (`$0.07`) + `$0.10` fixed fee = `$0.17`. When an incremental authorization is added, only the percentage fee (1%) applies to the additional amount—the fixed fee is not charged again.
The initial authorization includes both the percentage fee and the fixed fee:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_trD8QwHKEMY5YukFYKsDbRc",
"event_developer_id": "d0556c4f-405d-4d4d-8e2c-1ea8859baa33",
"event_sequence": 269516,
"event_category": "card_transaction",
"event_type": "card_transaction.created",
"event_object_id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"event_object_status": "approved",
"event_object": {
"id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"fees": {
"transaction_fee": {
"fee_amount": "-0.17",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.17"
},
"amount": "-7.34",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-22T13:47:56.982Z",
"updated_at": "2025-10-22T13:47:59.262Z",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"authorized_at": "2025-10-22T13:47:56.995Z",
"merchant_name": "SQ *BRIDGE CAFE",
"status_reason": "approved",
"billing_amount": "-6.12",
"card_account_id": "44a2f5c1-9f26-4bed-a6e3-601533148e6f",
"original_amount": "-7.34",
"merchant_location": "San Francisco, CAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.17",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.17"
},
"amount": "-7.34",
"wallet": "other",
"account": {
"last_4": "8739"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "CA",
"country": "USA",
"category": "eating_places_restaurants",
"description": "SQ *BRIDGE CAFE San FranciscoCAUS",
"postal_code": "94105",
"category_code": "5812"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-22T13:47:56.000Z",
"fee_amount": "0.00",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"card_present": true,
"entry_method": "contactless",
"international": false,
"status_reason": "approved",
"billing_amount": "-6.12",
"transaction_id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"approval_status": "approved",
"card_account_id": "44a2f5c1-9f26-4bed-a6e3-601533148e6f",
"cashback_amount": "0.00",
"authorization_id": "7502d7ae-a36f-5aca-8497-c4a7789452d4",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-6.12",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5812",
"transaction_description": "SQ *BRIDGE CAFE San FranciscoCAUS"
},
"event_object_changes": {},
"event_created_at": "2025-10-22T13:48:00.087Z"
}
```
When an additional amount is authorized (e.g., a tip), only the percentage fee applies to that amount. The incremental auth entry in `authorization_infos` shows the additional fee (`-0.01` = 1% of `$1.06`), while the top-level `fees` shows the updated total (`-0.18` = original `$0.17` + additional `$0.01`):
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_tnx8GPnonE2Fk7maYZ1vku5",
"event_developer_id": "d0556c4f-405d-4d4d-8e2c-1ea8859baa33",
"event_sequence": 269518,
"event_category": "card_transaction",
"event_type": "card_transaction.updated.status_transitioned",
"event_object_id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"event_object_status": "incremental_auth_approved",
"event_object": {
"id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"fees": {
"transaction_fee": {
"fee_amount": "-0.18",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.18"
},
"amount": "-8.4",
"status": "incremental_auth_approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-22T13:47:56.982Z",
"updated_at": "2025-10-22T13:48:05.284Z",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"authorized_at": "2025-10-22T13:47:56.995Z",
"merchant_name": "SQ *BRIDGE CAFE",
"status_reason": "approved",
"billing_amount": "-7.0",
"card_account_id": "44a2f5c1-9f26-4bed-a6e3-601533148e6f",
"original_amount": "-7.34",
"merchant_location": "San Francisco, CAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.01",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.01"
},
"amount": "-1.06",
"wallet": "other",
"account": {
"last_4": "8739"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "CA",
"country": "USA",
"category": "eating_places_restaurants",
"description": "SQ *BRIDGE CAFE San FranciscoCAUS",
"postal_code": "94105",
"category_code": "5812"
},
"auth_type": "incremental_auth",
"recurring": false,
"created_at": "2025-10-22T13:48:00.000Z",
"fee_amount": "0.00",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-0.88",
"transaction_id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"approval_status": "approved",
"card_account_id": "44a2f5c1-9f26-4bed-a6e3-601533148e6f",
"cashback_amount": "0.00",
"authorization_id": "6b9ca2a5-09e3-5a25-9108-accd9ac32533",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-0.88",
"currency": "usd",
"exchange_rate": "1.0"
},
"original_authorization_id": "7502d7ae-a36f-5aca-8497-c4a7789452d4"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.17",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.17"
},
"amount": "-7.34",
"wallet": "other",
"account": {
"last_4": "8739"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "CA",
"country": "USA",
"category": "eating_places_restaurants",
"description": "SQ *BRIDGE CAFE San FranciscoCAUS",
"postal_code": "94105",
"category_code": "5812"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-22T13:47:56.000Z",
"fee_amount": "0.00",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"card_present": true,
"entry_method": "contactless",
"international": false,
"status_reason": "approved",
"billing_amount": "-6.12",
"transaction_id": "6128b59d-6a6c-483b-ae6d-57b92edd3c33",
"approval_status": "approved",
"card_account_id": "44a2f5c1-9f26-4bed-a6e3-601533148e6f",
"cashback_amount": "0.00",
"authorization_id": "7502d7ae-a36f-5aca-8497-c4a7789452d4",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-6.12",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "5812",
"transaction_description": "SQ *BRIDGE CAFE San FranciscoCAUS"
},
"event_object_changes": {
"amount": [
"-7.34",
"-8.4"
],
"status": [
"approved",
"incremental_auth_approved"
],
"updated_at": [
"2025-10-22T13:47:59.262Z",
"2025-10-22T13:48:05.284Z"
],
"billing_amount": [
"-6.12",
"-7.0"
],
"authorization_infos": [
...
]
},
"event_created_at": "2025-10-22T13:48:06.116Z"
}
```
#### Authorization Reversal with Fee Refund
When a transaction is reversed before settlement, fees may be refunded depending on your configuration. In this example, fees are refunded and the `fees` object shows a net total of `0.0`:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_tw4T3wMJKXZ6Enc7VWrY6Zw",
"event_developer_id": "3c2a733c-e59d-4b0e-b302-2ab5b4472a38",
"event_sequence": 9458340,
"event_category": "card_transaction",
"event_type": "card_transaction.updated.status_transitioned",
"event_object_id": "726ca19d-27c7-42cc-bf3b-ab2426b958d8",
"event_object_status": "reversed",
"event_object": {
"id": "726ca19d-27c7-42cc-bf3b-ab2426b958d8",
"fees": {
"transaction_fee": {
"fee_amount": "0.0",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "0.0"
},
"amount": "0.0",
"status": "reversed",
"category": "purchase",
"currency": "usd",
"created_at": "2025-10-27T19:25:01.108Z",
"updated_at": "2025-10-27T19:26:27.163Z",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"authorized_at": "2025-10-27T19:25:01.128Z",
"merchant_name": "ROCKET RIDES SAN FRANCISCOCAUS",
"status_reason": "approved",
"billing_amount": "0.0",
"card_account_id": "665f8d7c-00fd-4e88-a9aa-64d68e988b80",
"original_amount": "-4.0",
"merchant_location": "SAN FRANCISCO, CAUS",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "0.14",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "0.14"
},
"amount": "4.0",
"wallet": "other",
"account": {
"last_4": "3405"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "CA",
"country": "USA",
"category": "miscellaneous_recreation_services",
"description": "ROCKET RIDES SAN FRANCISCOCAUS",
"postal_code": "941030000",
"category_code": "7999"
},
"auth_type": "reversal",
"recurring": false,
"created_at": "2025-10-27T19:26:26.000Z",
"fee_amount": "0.00",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "4.0",
"transaction_id": "726ca19d-27c7-42cc-bf3b-ab2426b958d8",
"approval_status": "approved",
"card_account_id": "665f8d7c-00fd-4e88-a9aa-64d68e988b80",
"cashback_amount": "0.00",
"authorization_id": "c5d1cf2b-31aa-5fa7-91e9-c29619cc8f94",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"three_d_secure_check": "authenticated",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "4.0",
"currency": "usd",
"exchange_rate": "1.0"
},
"original_authorization_id": "f76cc7da-3c76-5b62-8499-ac7fd2677f49"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.14",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": false
},
"total_fee_amount": "-0.14"
},
"amount": "-4.0",
"wallet": "other",
"account": {
"last_4": "3405"
},
"network": "visa",
"currency": "usd",
"merchant": {
"state": "CA",
"country": "USA",
"category": "miscellaneous_recreation_services",
"description": "ROCKET RIDES SAN FRANCISCOCAUS",
"postal_code": "941030000",
"category_code": "7999"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-10-27T19:25:00.000Z",
"fee_amount": "0.00",
"customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
"card_present": false,
"entry_method": "card_not_present",
"international": false,
"status_reason": "approved",
"billing_amount": "-4.0",
"transaction_id": "726ca19d-27c7-42cc-bf3b-ab2426b958d8",
"approval_status": "approved",
"card_account_id": "665f8d7c-00fd-4e88-a9aa-64d68e988b80",
"cashback_amount": "0.00",
"authorization_id": "f76cc7da-3c76-5b62-8499-ac7fd2677f49",
"partial_supported": false,
"verification_data": {
"cvv_check": "not_provided",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"three_d_secure_check": "authenticated",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-4.0",
"currency": "usd",
"exchange_rate": "1.0"
}
}
],
"merchant_category_code": "7999",
"transaction_description": "ROCKET RIDES SAN FRANCISCOCAUS"
},
"event_object_changes": {
"status": ["approved", "reversed"],
"amount": ["-4.0", "0.0"],
"billing_amount": ["-4.0", "0.0"]
},
"event_created_at": "2025-10-27T19:26:27.804Z"
}
```
The `authorization_infos` array contains both the original authorization (with negative fee) and the reversal (with positive fee, returning the fee to the cardholder). The top-level `fees.total_fee_amount` shows the net fee of `0.0`.
#### Authorization Expiration with Fee Refund
Authorizations can expire if the merchant does not complete the transaction within a certain time period (e.g., a hotel hold that is never settled). When an authorization expires, fees are **always refunded** to the cardholder.
When a card transaction is first approved, the fee is calculated and charged:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_t6peG8KvbTfHRKJXK2vdaU3",
"event_developer_id": "e2551449-d309-4b8f-8035-47323545d024",
"event_sequence": 10190914,
"event_category": "card_transaction",
"event_type": "card_transaction.created",
"event_object_id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"event_object_status": "approved",
"event_object": {
"id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"fees": {
"transaction_fee": {
"fee_amount": "-0.20",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": true
},
"total_fee_amount": "-0.20"
},
"amount": "-10.00",
"status": "approved",
"category": "purchase",
"currency": "usd",
"created_at": "2025-11-19T04:44:06.191Z",
"updated_at": "2025-11-19T04:46:17.629Z",
"customer_id": "6398ddae-a6a5-4f88-8086-e5b21f3ab6a0",
"authorized_at": "2025-11-19T04:44:06.208Z",
"merchant_name": "CENTRAL LIMA, PE",
"status_reason": "approved",
"billing_amount": "-10.00",
"card_account_id": "ce2b71b9-1179-4d9d-b644-690a4f7d935f",
"original_amount": "-10.00",
"merchant_location": "LIMA, PE",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.20",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": true
},
"total_fee_amount": "-0.20"
},
"amount": "-10.00",
"wallet": "other",
"account": {
"last_4": "7471"
},
"network": "visa",
"currency": "usd",
"merchant": {
"country": "PER",
"category": "eating_places_restaurants",
"description": "CENTRAL LIMA, PE",
"category_code": "5812"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-11-19T04:44:05.000Z",
"fee_amount": "0.00",
"customer_id": "6398ddae-a6a5-4f88-8086-e5b21f3ab6a0",
"card_present": true,
"entry_method": "contactless",
"international": true,
"status_reason": "approved",
"billing_amount": "-10.00",
"transaction_id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"approval_status": "approved",
"card_account_id": "ce2b71b9-1179-4d9d-b644-690a4f7d935f",
"cashback_amount": "0.00",
"authorization_id": "ac95da35-b154-42d7-8b74-646981a549f8",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-33.33",
"currency": "pen",
"exchange_rate": "0.3"
}
}
],
"merchant_category_code": "5812",
"transaction_description": "CENTRAL LIMA, PE"
},
"event_object_changes": {},
"event_created_at": "2025-11-19T04:46:19.881Z"
}
```
In this example, the fee is calculated as: 1% of `$10.00` (`$0.10`) + `$0.10` fixed fee = `$0.20`.
When the authorization expires without being settled, the fee is fully refunded. The `fees.total_fee_amount` becomes `0.0`:
```json expandable theme={null}
{
"api_version": "v0",
"event_id": "wh_tv5skiJkqZ2dSGay4rfsDFK",
"event_developer_id": "e2551449-d309-4b8f-8035-47323545d024",
"event_sequence": 10265365,
"event_category": "card_transaction",
"event_type": "card_transaction.updated.status_transitioned",
"event_object_id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"event_object_status": "expired",
"event_object": {
"id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"fees": {
"transaction_fee": {
"fee_amount": "0.0",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": true
},
"total_fee_amount": "0.0"
},
"amount": "0.0",
"status": "expired",
"category": "purchase",
"currency": "usd",
"created_at": "2025-11-19T04:44:06.191Z",
"updated_at": "2025-11-21T09:00:21.221Z",
"customer_id": "6398ddae-a6a5-4f88-8086-e5b21f3ab6a0",
"authorized_at": "2025-11-19T04:44:06.208Z",
"merchant_name": "CENTRAL LIMA, PE",
"status_reason": "approved",
"billing_amount": "0.0",
"card_account_id": "ce2b71b9-1179-4d9d-b644-690a4f7d935f",
"original_amount": "-10.00",
"merchant_location": "LIMA, PE",
"authorization_infos": [
{
"fees": {
"transaction_fee": {
"fee_amount": "0.20",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": true
},
"total_fee_amount": "0.20"
},
"amount": "10.00",
"wallet": "other",
"account": {
"last_4": "7471"
},
"network": "visa",
"currency": "usd",
"merchant": {
"country": "PER",
"category": "eating_places_restaurants",
"description": "CENTRAL LIMA, PE",
"category_code": "5812"
},
"auth_type": "expiration",
"recurring": false,
"created_at": "2025-11-21T09:00:21.000Z",
"fee_amount": "0.00",
"customer_id": "6398ddae-a6a5-4f88-8086-e5b21f3ab6a0",
"card_present": true,
"entry_method": "contactless",
"international": true,
"status_reason": "approved",
"billing_amount": "10.00",
"transaction_id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"approval_status": "approved",
"card_account_id": "ce2b71b9-1179-4d9d-b644-690a4f7d935f",
"cashback_amount": "0.00",
"authorization_id": "1d4fedc2-6e6b-4781-ae5d-c85fe6ccbdcf",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "33.33",
"currency": "pen",
"exchange_rate": "0.3"
},
"original_authorization_id": "ac95da35-b154-42d7-8b74-646981a549f8"
},
{
"fees": {
"transaction_fee": {
"fee_amount": "-0.20",
"fee_config": {
"percentage_fee_basis_points": 100,
"fixed_fee_amount": "0.1"
},
"is_international": true
},
"total_fee_amount": "-0.20"
},
"amount": "-10.00",
"wallet": "other",
"account": {
"last_4": "7471"
},
"network": "visa",
"currency": "usd",
"merchant": {
"country": "PER",
"category": "eating_places_restaurants",
"description": "CENTRAL LIMA, PE",
"category_code": "5812"
},
"auth_type": "auth",
"recurring": false,
"created_at": "2025-11-19T04:44:05.000Z",
"fee_amount": "0.00",
"customer_id": "6398ddae-a6a5-4f88-8086-e5b21f3ab6a0",
"card_present": true,
"entry_method": "contactless",
"international": true,
"status_reason": "approved",
"billing_amount": "-10.00",
"transaction_id": "5a0662c4-eee0-4d31-a659-3b7ef5927c78",
"approval_status": "approved",
"card_account_id": "ce2b71b9-1179-4d9d-b644-690a4f7d935f",
"cashback_amount": "0.00",
"authorization_id": "ac95da35-b154-42d7-8b74-646981a549f8",
"partial_supported": false,
"verification_data": {
"cvv_check": "match",
"pin_check": "no_pin_passed",
"address_check": "not_provided",
"address_postal_code_check": "not_provided"
},
"local_transaction_details": {
"amount": "-33.33",
"currency": "pen",
"exchange_rate": "0.3"
}
}
],
"merchant_category_code": "5812",
"transaction_description": "CENTRAL LIMA, PE"
},
"event_object_changes": {
"status": [
"approved",
"expired"
],
"amount": [
"-10.00",
"0.0"
],
"billing_amount": [
"-10.00",
"0.0"
],
"updated_at": [
"2025-11-19T04:46:17.629Z",
"2025-11-21T09:00:21.221Z"
]
},
"event_created_at": "2025-11-21T09:00:22.241Z"
}
```
When an authorization expires, the `authorization_infos` array contains both the original auth (with negative fee amount) and the expiration entry (with positive fee amount, returning the fee). The top-level `fees.total_fee_amount` shows the net fee of `0.0`, meaning the full fee was refunded.
#### Denied Transactions
Fees are **not charged** on denied transactions. The `fees` object will not appear in webhook payloads for denied transactions.
#### Refunds After Settlement
For refunds that occur after a transaction has settled (merchant credits), fees from the original transaction are **not returned** to the cardholder. The `fees` object will not appear in refund transaction webhooks.
## **Fees on Card Statements**
When transaction fees are enabled for your integration, card statements will surface fee information in two places:
### Statement Summary
The statement summary section includes a **Transaction Fees** row that shows the total transaction fees charged during the statement period. This row only appears when fees are enabled.
| **Field** | **Description** |
| :--------------- | :-------------------------------------------------------------------------------- |
| Transaction Fees | The sum of all per-transaction developer fees charged during the statement period |
### Activities Table
The activities table adds a **Transaction Fee** column next to each transaction entry. This column shows:
* The fee amount for that specific transaction (e.g., `-$1.50`)
* A dash (`-`) for transactions that have no associated fee
### How Statement Fees Are Calculated
Transaction fees on the statement are derived from the settled fee amount recorded on each posted transaction. They are included in the running balance calculation, meaning the statement's starting and ending balances account for both transaction amounts and their associated fees.
## **Fees and Refunds**
When a transaction is refunded or reversed, the handling of fees depends on your configuration and the type of refund:
| **Scenario** | **Fee Behavior** |
| :---------------------------------------- | :-------------------------------------------------------------------- |
| Auth reversal (refund before settlement) | Fee refund behavior is configurable per developer |
| Auth expiration | Fees are always refunded to the cardholder |
| Merchant credit (refund after settlement) | Fees from the original transaction are not returned to the cardholder |
Fee refund behavior for your integration is configured by Bridge during onboarding. Contact the Bridge team if you need to understand or modify how fees are handled for refunds.
## **Fees Payout**
Card transaction fees you collect are automatically withheld from each transaction and set aside in a ledger reserved for you. Fees are settled and **paid out monthly on the 5th of each month** to your configured external account.
### Payout Details
| **Detail** | **Description** |
| :--------------- | :----------------------------------------------------------------------------- |
| Payout frequency | Monthly, on the 5th of each month |
| Payout currency | Same as the card's base currency (regardless of original transaction currency) |
### Configuring Your Payout Account
To receive your fee payouts, you need to configure an external account using the [Configure a fee External Account API](/api-reference/developers/configure-a-fee-external-account). This is the bank account where Bridge will deposit your monthly fee payouts.