Fees

This page describes all fee types applied within e.PN, along with the rules that determine when each fee is charged.
Developers can use this reference to understand how user-specific fees are calculated and how they affect final transaction amounts.

Fee Types

The endpoint GET /dictionary/fees returns a list of fees applicable to the authenticated user.
Each fee has a type, description, and application logic.

Fee Type	Description
payment-new-merchant-default	Fee charged for funding the main e.PN account.
card-unblock	Fee charged for unblocking a card.
card-order-price	Fee charged for issuing a new card.
card-reorder-price	Fee charged for reissuing a card.
deposit	Fee applied when topping up a card balance.
decline	Fee charged for a declined bank transaction.
external-withdraw-usdt-trc20	Fee charged for withdrawing funds externally.
internal-withdraw	Fee charged for transferring funds from a card to the main e.PN account.
provider-transaction	Bank processing fee for a transaction.
restricted-operation-fine	Penalty fee for a restricted or prohibited transaction.
international	Base fee for an international transaction.
master-card-dom	Mastercard domestic (non-international) transaction fee.
master-card-international	Mastercard international transaction fee.
visa-dom	Visa domestic (non-international) transaction fee.
visa-international	Visa international transaction fee.
master-card-international-decline	Fee for a declined Mastercard international transaction.
visa-international-decline	Fee for a declined Visa international transaction.
master-card-international-reversal	Fee for a reversal of a Mastercard international transaction.
visa-international-reversal	Fee for a reversal of a Visa international transaction.
dom-reversal	Bank fee for a reversal of a domestic (non-international) transaction.
master-card-international-refund	Fee for a refund of a Mastercard international transaction.
visa-international-refund	Fee for a refund of a Visa international transaction.
dom-refund	Bank fee for a refund of a domestic (non-international) transaction.
provider-transaction-approved-international	Bank fee for an approved international transaction.

Fee Fields

Each fee object returned by the API contains the following fields:

• type — string. The unique fee identifier and the fee category.
• min — nullable number. Minimum transaction amount for which this fee becomes applicable. If null, no lower bound is enforced.
• max — nullable number. Maximum transaction amount for which this fee is applicable. If null, no upper bound is enforced.
• percent — nullable number. Percentage-based fee. Applied only if provided and fix is null.
• fix — nullable number. Fixed fee amount. Applied only if provided and percent is null.
• min_fix — nullable number. Used together with percent.
  If both percent and min_fix exist:
  • calculate the percentage fee,
  • if the result is below min_fix, the system applies min_fix,
  • otherwise the calculated percentage value is used.
• card_bin_uuids — array of strings. List of card BIN UUIDs to which the fee applies.
• card_tariffs_ids — array of integers. Card tariff IDs for which the fee is applicable.
• is_card_tariff_active — boolean. Indicates whether the fee applies to cards with an active tariff.
  • If the card has an active tariff OR the card is not yet issued, fees with is_card_tariff_active = true take priority.
  • Fees with is_card_tariff_active = false are used only for cards whose tariff matches card_tariffs_ids.
• start_date — nullable string. Start of the validity period. Returned in Y-m-d H:i:s format using the user's personal account timezone. The fee applies only if the current date is on or after this value.
• end_date — nullable string. End of the validity period. Returned in Y-m-d H:i:s format using the user's personal account timezone. The fee applies only if the current date is on or before this value.

Fee Applicability Algorithm

The system determines which fee should be applied using the following sequence:

1. Filter by fee type
   Select all fees where type matches the operation being performed.

2. Filter by validity period
   Keep only fees where:
   • start_date is null or current date ≥ start_date
   • end_date is null or current date ≤ end_date
   All dates are evaluated in the user's personal account timezone.

3. Filter by transaction amount
   Keep only fees where:
   • min is null or amount ≥ min
   • max is null or amount ≤ max

4. Filter by card attributes (if operation involves a card)
   If the card is already issued, the system always uses the card’s tariff ID:
   • card_tariffs_ids must contain the card’s tariff ID
   • card_bin_uuids must contain the card’s BIN UUID (if provided)
   If the card is not yet issued, only fees with is_card_tariff_active = true are considered.

5. Resolve priority when multiple fees match
   If several fees remain applicable after filtering, the priority is:

   1. fees with is_card_tariff_active = true
   2. fees where the card BIN matches
   3. fees with the narrowest min/max boundaries

6. Calculate the fee amount
   Fees may contain both fix and percent. The final fee is calculated using the unified formula:
   fee = (fix ?? 0) + (amount * (percent ?? 0)) / 100
   After calculation, if min_fix is present and the percentage part is lower than min_fix, the percentage part is replaced with min_fix.

7. Return the resulting fee
   The selected fee and the calculated amount are returned as the final fee for the operation.

Example

Below is an example demonstrating fee selection and calculation based on the full applicability algorithm.

Input Data

Operation: card deposit
Transaction amount: 80 USD
Card BIN UUID: "a1b2c3"
Card tariff ID: 4

Fees Returned by /dictionary/fees

Fee A

type: "deposit"
min: 0
max: 100
percent: 1.5
fix: null
min_fix: 2
card_bin_uuids: ["a1b2c3"]
card_tariffs_ids: [4]
is_card_tariff_active: false
start_date: null
end_date: null

Fee B

type: "deposit"
min: 0
max: 1000
percent: null
fix: 3
min_fix: null
card_bin_uuids: []
card_tariffs_ids: [5]
is_card_tariff_active: true
start_date: null
end_date: null

Algorithm Walkthrough

1. Filter by type
   Both Fee A and Fee B have type deposit → both kept.

2. Filter by validity period
   Both have no start/end limits → both kept.

3. Filter by amount
   Transaction amount (80) satisfies both ranges → both kept.

4. Resolve priority

   • Fee A matches card BIN UUID "a1b2c3".
   • Fee B does not provide BIN matching.
     → Fee A is selected.

5. Calculate the fee
   Using the unified formula:
   fee = (fix ?? 0) + (amount * (percent ?? 0)) / 100
   For Fee A: fix = 0, percent = 1.5 → (0) + (80 * 1.5 / 100) = 1.20
   Since min_fix = 2 and 1.20 < 2, the percentage part becomes 2.
   Final fee = 2 USD.

Result

Final fee: 2.00 USD
Final amount charged: 82.00 USD
Fee applied: Fee A