> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Payor fees

> Learn how payor fees work in Payabli and how to configure and send them on transactions

Payabli supports multiple fee types that can be charged to the payor, such as convenience, service, surcharge, and platform or technology fees. Partners can submit the fee via API, or have Payabli automatically calculate and apply it on hosted payment solutions like payment pages and virtual terminals.

Whatever the fee type, Payabli carries it through a single value — the `serviceFee` field in the API, shown as Service Fee in the Payabli Portal. There's no separate field per fee type; the fee is set up as part of your paypoint's pricing configuration.

## Considerations

Keep these considerations in mind when working with payor fees in Payabli.

* Card networks govern fees. Before you decide on your fee strategy, talk with the Payabli team to learn about best practices.
* Payabli helps you configure fee structure during merchant boarding.
* You must contact Payabli support to change fees or configuration options.
* Fees are non-refundable. Contact the Payabli team for guidance on the appropriate messaging to display at checkout.

## Fee configuration

In addition to setting a percentage or dollar amount for fees, there are other configuration options. Contact Payabli to change these settings. See the [API transaction examples section](/guides/pay-in-payor-fees-overview#api-transaction-examples) for examples of how these settings work.

| Setting                                 | Description                                                                                                                                                                   |
| :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Absorb difference?*                    | If `true`, when a `serviceFee` that's less than the paypoint's configured fee is passed in a transaction, the merchant absorbs the difference. The default setting is `false` |
| *Accept greater value allowed for fee?* | If `true`, the system accepts `serviceFee` values on transactions higher than the amount configured in the paypoint's settings. The default setting is `true`.                |

An additional setting lets you override the configured fee on individual transactions. Contact the Payabli team to discuss whether this option is right for your merchants.

## Fees with API transactions

To charge a fee when running transactions via an API request or an embedded component, you must include the `serviceFee` value and a `totalAmount` value that includes the transaction amount plus the fee. The `serviceFee` is always a dollar amount, not a percentage.

If Payabli API receives `totalAmount` and `serviceFee`, the system compares the values to the pricing configuration for the paypoint.

System compares these values with configuration settings based on calculated `serviceFee` amount:

* If `serviceFee` is equal to the calculated value from the pricing configuration, then the transaction goes through. Payabli compares to 2 decimals and accepts a `serviceFee` plus or minus 1 penny.
* If `serviceFee` is greater than the calculated value from the pricing configurations, and if “Accept Greater value allowed config” is true, the fee goes through. If false, then entire transaction is rejected with return code `5006`.
* If `serviceFee` is less than the calculated value from the pricing configuration,  and “Absorb difference?” is `true` then the fee transmitted is processed, but the merchant absorbs the price difference. If false, then entire transaction is rejected with return code `5005`.

### API transaction examples

#### Absorb fee example

In these examples, a 3% fee is configured for the paypoint.

**Example 1:**

With the Absorb fee configuration option set to `true`, the merchant runs a transaction with a \$100.00 subtotal, plus a \$1.00 fee. The payor pays \$101.00 total. This leaves the merchant to pay the \$2.00 difference. \$98.00 is transferred to the merchant when the batch is funded.

**Example 2:**

With the Absorb fee configuration option set to `false`, the merchant sends a fee of \$1.00 with the transaction. The API returns a `5005` error code because the fee sent is less than the amount configured at the paypoint level. The system expects a 3% fee, which would equal \$3.00 on the \$100.00 subtotal, and the paypoint isn't set up to absorb a fee difference.

#### Fee greater than configured fee example

In these examples, a 3% fee is configured for the paypoint.

**Example 1:**

The *Accept greater value allowed for fee?* configuration is set to `true`. The merchant makes a transaction via the API. The subtotal is \$100. According to the paypoint's fee setting, the fee should be equal to \$3.00. Instead, the merchant adds a \$5.00 fee, for a grand total of \$105.00. This fee equals 5%. The fee is accepted and the transaction goes through. The merchant receives \$100.00 when the batch is funded and the payor is charged \$105.00.

**Example 2:**

The *Accept greater value allowed for fee?* configuration is set to `false`. You make a transaction via the API. The subtotal is \$100.00. You add a \$4.00 fee, for a grand total of \$104.00. This fee equals 4%. The fee is rejected with a `5006` error code, and the transaction doesn't go through.

## Fees with UI transactions

Configuring fees at the paypoint level automatically applies the fees to every transaction the paypoint runs using any of Payabli's hosted payment solutions. You only need to explicitly send fee amounts when making transactions using the API or embedded components.