Fee Type Configuration Parameters

There are multiple ways in which fees can be applied on the Platform:

Directly to Entities - Applied to individual Merchants or Referrers
Using Groups - Applied to a group of Merchant or Referrer entities.
Per Transaction - Applied to Entities or Groups as each transaction is processed. (Fee Listener)

Now that you’re familiar with the Fee Structure and available setup options, we’ll get started by setting up the Fee type of your choice using your preferred method.

Tip: If you are familiar with basic fee structure information, jump ahead to the Setting up a Fee section below.

Getting Started

Before you begin, it’s important to understand the makeup of a Fee configuration and the various components used to create the Fee setup exactly to your specifications.

Each section below covers the major components of setting up a fee with all available customizations and refinements. Each of these major steps is provided with a Portal setup guide and an API setup guide to offer instructions for your preferred platform usage method:

Setting up a Fee - Learn the process of how and where to set up a Fee.
Fee Type Setups - Learn the specific parameters required to set specific types of Fees.
Adding Fee Rules - Learn the process of adding Fee rules to further refine Fee Schedule (Trigger) criteria.

Prerequisites

To ensure your experience is streamlined, make sure you’re familiar with the following information:

Fee Types - The different categories of fees that can be created and charged.
Fee Structure - Overview of the basic layout for a Fee configuration.
- Fee Schedules - Available time or event-based triggers used to initiate a Fee charge.
- Fee Rules - Options to further refine the criteria of the Fee Schedule.
- Fee Modifiers - Options to redirect the Fee collection flow and who will pay the Fee.
- Fee Collection Process - Overview of how Fee payments are collected and where they can be found.

Warnings

Review the following warnings before you begin to avoid issues and potential legal complications:

Warning: Do not create or apply Surcharges as legal complications can occur. Visa and MasterCard specifically prohibit the application of Surcharges to cardholders on their card brand networks respectively.

Warning: Convenience Fees can only be charged to customers using an alternative payment method (e.g. a website instead of in-person or mail/telephone orders)

Tips

The following tips will provide you with extra insight useful to the process:

Tip: If you’re unsure of how much to charge for specific fee types, refer to the Visa and MasterCard card brand network guidelines

Setting up a Fee

This quick overview will demonstrate the steps necessary to begin setting up the Fee configuration of your choice. For simplicity, this will serve as the foundation to set up all Fee Types. Each Fee Type will be covered in its own section with additional context added where necessary.

Using the Portal

Click here for steps to begin setting up a Fee for an Entity (Merchant).

Step 1: Navigate to the Merchants page, located under Management.

Step 2: Click the Merchant you want to charge the Fee to enter its Merchant Profile page.

Step 3: In the Merchant Profile, click Fees from the left-hand menu. Then, click the ADD FEES button to reveal the Add Fee lightbox.

Step 4: Jump to the Fee Type of your choice below for the parameters required in the Add Fee lightbox.

Click here for steps to begin setting up a Fee for a Group.

Step 1: Navigate to the Groups page (located under Management).

Step 2: Select the Group the fee will be applied to from the page list or create a new Group with the ADD GROUP button and select the desired Merchant(s) from the list. Then, enter the Group’s Profile page.

Step 3: In the Group Profile, select Fees from the left-hand menu. Then, click the ADD FEES button to reveal the Add Fee lightbox.

Step 4: Jump to the Fee Type of your choice below for the parameters required in the Add Fee lightbox.

Click here for steps to begin setting up a Fee on a per-transaction basis.

Follow the steps in the applicable content above if you wish to apply this fee for an individual Merchant entity or to a Group [of Merchants]. Continue from Step 4.

Step 5: Check the Transaction Fee checkbox to enable the Fee to be charged on a per-transaction basis.

Using the API

As the API request offers the ability to set up all types of fees using the same call, we’ll provide the initial API reference information so you just have to change a few parameters (provided in each setup below)

Request URL & Headers

CODE

POST /fees HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com

The Request and Response bodies will use the same parameters for each Fee Type setup. We’ll provide you with an example request body and parameter descriptions so you’ll know what to change in the following setup steps.

Request Body Example - Fee for Account Overdraft

In this basic example, we’re setting up a $15.00 Platform Account Overdraft Fee.

This actual fee ("type": 1) will be paid by one entity (Referrer) on behalf of another (Merchant) when that (Merchant's) entity's available balance is overdrafted ("schedule": 12).

We’ve applied this setting to that Merchant’s entire Group (org) so all other Merchants assigned to the same Group will have the same Fee configuration applied to them.

JSON

{
  "type": "1",
  "schedule": 12,
  "um": 2,
  "currency": "USD",
  "txnFee": "0",
  "inactive": "0",
  "frozen": "0",
  "entity": "t1_ent_1xxxxxxxxxxxxx",
  "forentity": "t1_ent_2xxxxxxxxxxxxx",
  "org": "t1_org_xxxxxxxxxxxxxx",
  "name": "Example Fee",
  "description": "Example Fee for platform account overdraft.",
  "scheduleFactor": 0,
  "start": 20231111,
  "finish": 0,
  "collection": "1",
  "collectionFactor": 0,
  "collectionOffset": 0,
  "collectionIncludeCurrent": 0,
  "amount": "1500"
}

Request Body Parameters

Parameter	Type	Required	Description	Valid Values
`entity`	string	Required	The entity ID for the entity the Fee is being applied to.
`org`	string	Optional	The Org ID for the group the Fee is being applied to. Note: Leaving this field blank will apply the fee directly to the Merchant instead of their associated group overall.
`type`	integer	Required	The Type of Fee	Valid Values: `1` - Fee. A Standard Fee. `2` - Assessment. A Third-Party Platform Fee.
`name`	string	Optional	Custom name for the Fee.
`description`	string	Optional	Custom secondary description of the Fee.
`schedule`	integer	Required	The Fee trigger.	Valid Values: `1` - Days. The Fee is charged every day. `2` - Weeks. The Fee is charged every week. `3` - Months. The Fee is charged every month. `4` - Years. The Fee is charged every year. `5` - Single. The Fee is a one-off charge. `6` - Auth. The Fee is triggered at the time of authorization of a transaction. `7` - Capture. The Fee triggers at the capture time of a Transaction. `8` - Refund. The Fee triggers when a refund transaction is processed. `9` - Board. The Fee triggers when the Merchant is boarded `10` - Payout. The Fee triggers when a payout is processed. `11` - Chargeback. The Fee triggers when a card chargeback occurs. `12` - Overdraft. The Fee triggers when an overdraft usage charge from a bank is levied. `13` - Interchange. The Fee triggers when interchange default are assessed for the Transactions of this Merchant. `14` - Processor. The Fee triggers when the Transactions of this Merchant are processed by a payment processor. `15` - ACH failure. The Fee triggers when an automated clearing house failure occurs. `16` - Account. The Fee triggers when a bank account is verified. `17` - Sift. The Fee triggers when a txn uses SIFT for fraud checking. `18` - Adjustment. The Fee triggers when an adjustment is created. `19` - Retrieval. The Fee triggers when a chargeback retrieval is processed. `20` - Arbitration. The Fee triggers when a chargeback arbitration is processed. `21` - eCheck Sale. The Fee triggers when an eCheck sale is processed. `22` - eCheck Refund. The Fee triggers when an eCheck refund is processed. `23` - eCheck Return. The Fee triggers when an eCheck txn is returned because of a failure while processing. `24` - Settlement. The Fee triggers when a txn is settled. `25` - Misuse. The Fee triggers when a txn authorization is misused. `26` - Profit share. The Fee triggers when a profit share is executed. `27` - Unauth. The Fee triggers when an auth reversal is created. `28` - Disbursement NOC. The Fee triggers on Notice Of Change events for Disbursements. `29` - Transaction NOC. The Fee triggers on Notice Of Change events for Transactions. `30` - eCheck failure return. The Fee triggers when an eCheck txn is returned due to customer rejection or incorrect account information. `31` - eCheck NSF return. The Fee triggers when an eCheck txn is returned due to insufficient funds. `32` - Currency conversion. The Fee triggers when there is a currency converstion on a transaction. `33` - Terminal transaction. The Fee triggers when there is a transaction processed via a terminal. `34` - Reverse payout. The Fee triggers when a payout is reversed. `35` - Partial reverse payout. The Fee triggers when a payout is partially reversed. `36` - Reserve Entry. The Fee triggers when a new Reserve Entry is created. `37` - Reserve Entry Release. The Fee triggers when a Reserve of funds (Reserve Entry) has been released. `38` - Pending Entry. The Fee triggers when a Entry is created but still pending funding. `39` - Pending Paid. The Fee triggers when a Pending Entry has been fully funded and is no longer in Pending status. `40` - Remainder. The Fee triggers when a remainder of less than a whole value (.01) is created, `41` - Remainder Used. The Fee triggers when any remainder leftover is used/paid out in the next applicable withdrawal. 42 - Pending Refund Cancelled. The Fee triggers when a Fee refund is issued, then cancelled before passing the Pending status for funding and withdrawal. `43` - Payment check. The Fee triggers on a payment check. `44` - Payment update. The Fee triggers when a payment is updated. `45` - Payment group check. The Fee triggers on a payment group check. `46` - Payment group update. The Fee triggers on a payment group update. `47` - Entry refund. The Fee triggers when a entry is refunded. `48` - Entity Reserve change - A reserve on an entity has been modified. `49` - Release Hold - A Transaction hold has been released. `50` - Release Entries - Multiple held entries have been released. `51` - Statement Payment - A statement bill was paid. `52` - Merchant Created - A new Merchant entity has been created, but not boarded. `53` - Realtime Business Search - Real-time Business Entity OFAC Search from Bridger by LexisNexis. `54` - Realtime Member Search - Real-time Business Entity Managing Member Personal OFAC Search from Bridger by LexisNexis. `55` - MasterCard MATCH - Merchant History Check from Mastercard Alert To Control High-risk Merchants (MATCH) program. `56` - Business Instant ID - KYB Verification from LexisNexis `57` - Consumer Instance ID - KYC Verification from LexisNexis. `58` - ThreatMetrix - Black List & OFAC Watchlist check from LexisNexis `59` - LegitScript Registration - Merchant Compliance and Risk Rating Checks. `60` - Equifax Consumer Report - Business owner's consumer credit report from Equifax. `61` - CharityCheck - Business entity nonprofit eligibility verification from GuideStar. `62` - Internal Decision V2 - Payrix Risk services decision. `63` - TIN Check - Tax Identification Number matching service for tax identity management from Sovos. `64` - Equifax Commercial Report - Entity's commercial credit report from Equifax. `65` - LegitScript Merchant Check - Merchant Compliance and Risk Rating Checks. `66` - Plaid - Bank account link, info update and verification services. `67` - Statement Reversal - A statement eCheck payment was reversed. `68` - GIACT eCheck Verification - Real-time account status check for consumer and business bank accounts from gVerify by GIACT. `69` - GIACT Account Verification - Real-time Business Entity Owner identity & authorized signer status verification from gAuthenticate by GIACT. `70` - Boarding Decision - Merchant boarding decision made by the platform via risk checks. `71` - Transaction Risk Decision - Transaction decision made by the platform via risk checks. `72` - FANF - Fixed Acquirer Network Fee from Visa for Merchants processing card-present and card-not-present transactions. `73` - MCLocation - Merchant Location Fee from Mastercard for Merchants processing card-present and card-not-present transactions. `74` - VisaIntegrity - Transaction Integrity Fee from Visa `75` - SaferPayments: Basic - PCI DSS Compliance Portal from WorldPay for Referrer and Facilitator Merchant portfolios. `76` - SaferPayments: Managed - PCI DSS Compliance Managed Services from WorldPay for Merchants in Referrer and Facilitator portfolios. `77` - SaferPayments - PCI Non-Validation - PCI DSS Compliance Portal and/or services were provided but the Merchant failed to meet PCI DSS Compliance. `78` - OmniToken - Omni-Channel payment tokenization from WorldPay `79` - Payout Return - A Payout Disbursement was returned when attempted. `80` - Payout Partial Return - A Payout Disbursement was partially returned when attempted. `81` - Revenue Share - A configuration of multiple entities dividing revenue. `82` - Card Settlement. The funds from a card payment captured and authorized in a transaction have been settled. `83` - eCheck Settlement. The funds from an ACH/eCheck payment used in a transaction have been settled. `84` - Revenue Share from Card - Funds have been captured in a Revenue Share configuration from a card payment transaction. `85` - Revenue Share from eCheck - Funds have been captured in a Revenue Share configuration from an ACH / eCheck payment transaction. `86` - Revenue Share Payout - Funds from a Revenue Share capture have been settled and disbursed to the applicable entities.
`scheduleFactor`	string	Required	A multiplier that you can use to adjust the schedule set in the 'schedule' field, if it is set to a duration-based trigger, such as daily, weekly, monthly, or annually. This field is specified in basis points and its value determines how the interval is multiplied..	Format: `2.00` = every 2 Days (if `days` is chosen as the `schedule` for example).
`start`	string	Required	The date that the Fee will take effect.	Format: `YYYYMMDD`
`collection`	integer	Required	Applies the fee based on the volume of a resource.	Valid Values: `1` - Txn. The total amount of all transactions. `2` - Txn-TaxID. The total amount of all transactions per entity EIN/tax ID. `3` - Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	integer	Required	A multiplier that you can use to adjust the set of data to be used in the collection calculation. This field is specified in basis points and its value determines the period of time to be used.	Format: `2.00` = 2x multiplier.
`collectionOffset`	string	Required	The number of days, weeks, months or years to go back when selecting data for collection calculation.	Format: Whole numerical values. Example: `1`
`um`	integer	Required	The unit of measure for this Fee. Warning: Percentage and Surcharge units will only apply to Fee schedules set to trigger from monetary events, such as an authorization, capture, or refund.	Valid Values: `1` - Percentage. The Fee is a percentage of the related event amount, specified in the 'amount' field in basis points. `2` - Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. `3` - Surcharge. The Fee is a percentage of the related event amount as a surcharge (the calculated amount will be based on the assumption that the related event amount already contains the fee amount in it), specified in the 'amount' field in basis points.
`currency`	string	Required	The three-digit symbol for the currency that the Fee will be charged and collected in.	Valid Values: `USD` `CAD`
`txnFee`	integer	Required	Indicator to extract fee from txn supplied fee. When set, amount will correspond to the fee amount in the txn and only that amount will be extractable, anything over that amount will not be extracted.	Valid Values: `0` - Disabled. Fee will be calculated normally. `1` - Enabled. Fee will be calculated based on transaction fee.
`inactive`	integer	Required	Whether or not this fee is active.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Required	Whether or not this fee is temporarily frozen.	Valid Values: `0` - Not frozen `1` - Frozen

Response Body Example - Fee for Account Overdraft

In the response, we see the new Fee ID (the id parameter) which can be used to later change or recall the fee when necessary. You’ll now also see new information about who created the Fee configuration and when (e.g. created & creator).

CODE

{
      "id": "t1_fee_xxxxxxxxxxxxxx",
      "created": "2023-10-25T19:10:44.278Z",
      "modified": "2023-10-25T19:10:44.278Z",
      "creator": "t1_log_xxxxxxxxxxxxxx",
      "modifier": "t1_log_xxxxxxxxxxxxxx",
      "entity": "t1_ent_1xxxxxxxxxxxxx",
      "forentity": "t1_ent_2xxxxxxxxxxxxx",
      "org": "t1_org_xxxxxxxxxxxxxx",
      "type": "1",
      "name": "Example Fee",
      "description": "Example Fee for platform account overdraft.",
      "schedule": "12",
      "scheduleFactor": 0,
      "start": 20231111,
      "finish": 0,
      "collection": "1",
      "collectionFactor": 0,
      "collectionOffset": 0,
      "collectionIncludeCurrent": 0,
      "um": "2",
      "amount": "1500",
      "currency": "USD",
      "txnFee": "0",
      "inactive": "0",
      "frozen": "0"
    }

Response Body Parameters

Parameter	Type	Description	Valid Values
`id`	string	The ID of the newly created Fee.
`created`	string	The Date and Time that the Fee was created.
`modified`	string	The Date and Time that the Fee was last modified.
`creator`	string	The Login ID for the user that created the Fee.
`modifier`	string	The Login ID for the user that last modified the Fee.
`entity`	string	The entity ID for the entity the Fee is being applied to.
`org`	string	The Org ID for the group the Fee is being applied to.
`type`	integer	The type of Fee being charged to the entity.	Valid Values: `1` - Fee. A Standard Fee. `2` - Assessment. A Third-Party Platform Fee.
`name`	string	Custom name for the Fee.
`description`	string	Custom secondary description of the Fee.
`schedule`	integer	The Fee trigger.	Valid Values: `1` - Days. The Fee is charged every day. `2` - Weeks. The Fee is charged every week. `3` - Months. The Fee is charged every month. `4` - Years. The Fee is charged every year. `5` - Single. The Fee is a one-off charge. `6` - Auth. The Fee is triggered at the time of authorization of a transaction. `7` - Capture. The Fee triggers at the capture time of a Transaction. `8` - Refund. The Fee triggers when a refund transaction is processed. `9` - Board. The Fee triggers when the Merchant is boarded `10` - Payout. The Fee triggers when a payout is processed. `11` - Chargeback. The Fee triggers when a card chargeback occurs. `12` - Overdraft. The Fee triggers when an overdraft usage charge from a bank is levied. `13` - Interchange. The Fee triggers when interchange default are assessed for the Transactions of this Merchant. `14` - Processor. The Fee triggers when the Transactions of this Merchant are processed by a payment processor. `15` - ACH failure. The Fee triggers when an automated clearing house failure occurs. `16` - Account. The Fee triggers when a bank account is verified. `17` - Sift. The Fee triggers when a txn uses SIFT for fraud checking. `18` - Adjustment. The Fee triggers when an adjustment is created. `19` - Retrieval. The Fee triggers when a chargeback retrieval is processed. `20` - Arbitration. The Fee triggers when a chargeback arbitration is processed. `21` - eCheck Sale. The Fee triggers when an eCheck sale is processed. `22` - eCheck Refund. The Fee triggers when an eCheck refund is processed. `23` - eCheck Return. The Fee triggers when an eCheck txn is returned because of a failure while processing. `24` - Settlement. The Fee triggers when a txn is settled. `25` - Misuse. The Fee triggers when a txn authorization is misused. `26` - Profit share. The Fee triggers when a profit share is executed. `27` - Unauth. The Fee triggers when an auth reversal is created. `28` - Disbursement NOC. The Fee triggers on Notice Of Change events for Disbursements. `29` - Transaction NOC. The Fee triggers on Notice Of Change events for Transactions. `30` - eCheck failure return. The Fee triggers when an eCheck txn is returned due to customer rejection or incorrect account information. `31` - eCheck NSF return. The Fee triggers when an eCheck txn is returned due to insufficient funds. `32` - Currency conversion. The Fee triggers when there is a currency converstion on a transaction. `33` - Terminal transaction. The Fee triggers when there is a transaction processed via a terminal. `34` - Reverse payout. The Fee triggers when a payout is reversed. `35` - Partial reverse payout. The Fee triggers when a payout is partially reversed. `43` - Payment check. The Fee triggers on a payment check. `44` - Payment update. The Fee triggers when a payment is updated. `45` - Payment group check. The Fee triggers on a payment group check. `46` - Payment group update. The Fee triggers on a payment group update. `47` - Entry refund. The Fee triggers when a entry is refunded. `48` - Entity Reserve change - A reserve on an entity has been modified. `49` - Release Hold - A Transaction hold has been released. `50` - Release Entries - Multiple held entries have been released. `51` - Statement Payment - A statement bill was paid. `52` - Merchant Created - A new Merchant entity has been created, but not boarded. `53` - Realtime Business Search - Real-time Business Entity OFAC Search from Bridger by LexisNexis. `54` - Realtime Member Search - Real-time Business Entity Managing Member Personal OFAC Search from Bridger by LexisNexis. `55` - MasterCard MATCH - Merchant History Check from Mastercard Alert To Control High-risk Merchants (MATCH) program. `56` - Business Instant ID - KYB Verification from LexisNexis `57` - Consumer Instance ID - KYC Verification from LexisNexis. `58` - ThreatMetrix - Black List & OFAC Watchlist check from LexisNexis `59` - LegitScript Registration - Merchant Compliance and Risk Rating Checks. `60` - Equifax Consumer Report - Business owner's consumer credit report from Equifax. `61` - CharityCheck - Business entity nonprofit eligibility verification from GuideStar. `62` - Internal Decision V2 - Payrix Risk services decision. `63` - TIN Check - Tax Identification Number matching service for tax identity management from Sovos. `64` - Equifax Commercial Report - Entity's commercial credit report from Equifax. `65` - LegitScript Merchant Check - Merchant Compliance and Risk Rating Checks. `66` - Plaid - Bank account link, info update and verification services. `67` - Statement Reversal - A statement eCheck payment was reversed. `68` - GIACT eCheck Verification - Real-time account status check for consumer and business bank accounts from gVerify by GIACT. `69` - GIACT Account Verification - Real-time Business Entity Owner identity & authorized signer status verification from gAuthenticate by GIACT. `70` - Boarding Decision - Merchant boarding decision made by the platform via risk checks. `71` - Transaction Risk Decision - Transaction decision made by the platform via risk checks. `72` - FANF - Fixed Acquirer Network Fee from Visa for Merchants processing card-present and card-not-present transactions. `73` - MCLocation - Merchant Location Fee from Mastercard for Merchants processing card-present and card-not-present transactions. `74` - VisaIntegrity - Transaction Integrity Fee from Visa `75` - SaferPayments: Basic - PCI DSS Compliance Portal from WorldPay for Referrer and Facilitator Merchant portfolios. `76` - SaferPayments: Managed - PCI DSS Compliance Managed Services from WorldPay for Merchants in Referrer and Facilitator portfolios. `77` - SaferPayments - PCI Non-Validation - PCI DSS Compliance Portal and/or services were provided but the Merchant failed to meet PCI DSS Compliance. `78` - OmniToken - Omni-Channel payment tokenization from WorldPay `79` - Payout Return - A Payout Disbursement was returned when attempted. `80` - Payout Partial Return - A Payout Disbursement was partially returned when attempted. `81` - Revenue Share - A configuration of multiple entities dividing revenue. `82` - Card Settlement. The funds from a card payment captured and authorized in a transaction have been settled. `83` - eCheck Settlement. The funds from an ACH/eCheck payment used in a transaction have been settled. `84` - Revenue Share from Card - Funds have been captured in a Revenue Share configuration from a card payment transaction. `85` - Revenue Share from eCheck - Funds have been captured in a Revenue Share configuration from an ACH / eCheck payment transaction. `86` - Revenue Share Payout - Funds from a Revenue Share capture have been settled and disbursed to the applicable entities.
`scheduleFactor`	string	A multiplier that you can use to adjust the schedule set in the 'schedule' field, if it is set to a duration-based trigger, such as daily, weekly, monthly, or annually. This field is specified in basis points and its value determines how the interval is multiplied.	Format: `2.00` = 2x multiplier.
`start`	string	The date that the Fee will take effect.	Format: `YYYYMMDD`
`collection`	integer	Applies the fee based on the volume of a resource.	Valid Values: `1` - Txn. The total amount of all transactions. `2` - Txn-TaxID. The total amount of all transactions per entity EIN/tax ID. `3` - Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	integer	A multiplier that you can use to adjust the set of data to be used in the collection calculation. This field is specified in basis points and its value determines the period of time to be used.	Format: `2.00` = 2x multiplier.
`collectionIncludeCurrent`		Whether to include the current period for the colleciton calculation.	Valid Values: `0` - Include `1` - Don’t inlcude
`um`	integer	The unit of measure for this Fee. Warning: Percentage and Surcharge units will only apply to Fee schedules set to trigger from monetary events, such as an authorization, capture, or refund.	Valid Values: `1` - Percentage. The Fee is a percentage of the related event amount, specified in the 'amount' field in basis points. `2` - Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. `3` - Surcharge. The Fee is a percentage of the related event amount as a surcharge.
`amount`	string
`maximum`	string
`currency`	string	The three-digit symbol for the currency that the Fee will be charged and collected in.	Valid Values: `USD` `CAD`
`txnFee`	integer	Indicator to extract fee from txn supplied fee. When set, amount will correspond to the fee amount in the txn and only that amount will be extractable, anything over that amount will not be extracted.	Valid Values: `0` - Disabled. Fee will be calculated normally. `1` - Enabled. Fee will be calculated based on transaction fee.
`inactive`	integer	Whether or not this fee is active.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Whether or not this fee is temporarily frozen.	Valid Values: `0` - Not frozen `1` - Frozen

Fee Type Setups

In the Fee Type Setup steps below, we’ll simply include the required parameter settings necessary to enable that particular Fee Type. Additional context and information will be provided within each section.

Choose the Fee Type you’d like to set:

Boarding Fees - Fees collected from your Merchants as they board the platform.
Chargeback/Dispute Fees - Fees collected for managing Merchants’ dispute responses.
Convenience Fees - Fees collected from Cardholders for alternative payment method acceptance.
External Fees - Fees collected for services provided outside of the platform such as Visa Fixed Acquirer Network Fee (FANF), Visa Integrity Fees, and MasterCard Merchant Location Fees or Value-Added Services like OmniToken and SaferPayments.
Interchange & Processing Fees - Fees collected to reimburse Interchange and other costs assessed by the processor and/or card brands.
Platform Service Fees - Fees collected for custom Platform Service enablement
Risk Decision Fees - Fees collected for triggering automated Risk Decisions on an entity.
Risk Service Fees - Fees collected for performing a Risk Policy check on an entity at a cost.
Surcharge Fees - Fees collected from cardholders by Merchants as an additional charge, usually to cover specific costs associated with the transaction, such as platform transaction fees.
Transaction Fees - Fees collected when transactions are authorized and/or captured.

Tip: If you’re already familiar with the essential Fee Type setups, jump ahead to Fee Rules to learn how to further refine the Schedule (Triggers) of your Fees.

Boarding Fees

This customization allows our partners to seamlessly implement a portfolio-wide or individual new account creation fee to collect from their clients.

Example: As a Facilitator, you would like to charge a Fee to your Referrers for boarding Merchants and to that Referrer’s Merchants whenever they board Sub-Merchants. This Fee allows the Facilitator to generate revenue from Merchant boarding under their portfolio, even if the Merchant ultimately has little or no activity after boarding.

Boarding Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Board	The Fee triggers when the Merchant is boarded.
How much is the fee?	Actual
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.

Boarding Fee Setup Parameters - API

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`9`	Board. The Fee triggers when the Merchant is boarded
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`0`	Disabled Transaction Fee
`collection`	`1`
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Chargeback Fees

Chargeback Fees (also known as Dispute Fees) are fees set and charged to Merchants by Referrers for offering the platform to process the Chargeback.

Example: A Merchant has received an initial dispute opening the chargeback process, also known as Retrieval. When a Chargeback Fee is configured and “Retrieval” is chosen as the Fee Schedule (Trigger) ("schedule": 19) , the Merchant will now be assessed a fee when the Chargeback Cycle is opened and Dispute Stage is “Retrieval”

Begin by following the steps in the Setting up a Fee section under the Using the Portal steps and use the parameters below to complete the process.

Chargeback Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Chargeback	This fee triggers when a first chargeback dispute stage is reached against a Merchant. You can also use the following options for different Chargeback cycles: Retrieval. The Fee triggers when a Retrieval dispute stage is reached against a Merchant. Arbitration. The Fee triggers when an Arbitration dispute stage is reached against a Merchant.
How much is the fee?	Actual
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `2.50` = $2.50).
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.

This Fee is now configured to trigger to charge a Merchant whenever a Chargeback is created (First Chargeback Dispute Stage).

Chargeback Fee Setup Parameters - API

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`11`	Chargeback. The Fee triggers when a first chargeback dispute stage is reached against a Merchant. You can also use the following options for different Chargeback cycles: `19` - Retrieval. The Fee triggers when a Retrieval dispute stage is reached against a Merchant. `20` - Arbitration. The Fee triggers when an Arbitration dispute stage is reached against a Merchant.
`scheduleFactor`	`0`
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`0`	Disabled Transaction Fee
`collection`	`3`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

This Fee is now configured to trigger to charge a Merchant whenever a Chargeback is created (First Chargeback Dispute Stage).

Convenience Fees

Convenience Fees are fees set and charged by Merchants to Cardholders for the “alternative” payment method acceptance. “Alternative” refers to the non-primary payment methods provided by Merchants to Cardholders. This Convenience Fee amount is then charged to the Merchant by the Referrer, based on the Referrer’s Fee Modifier settings.

Example: A Merchant that typically accepts in-person payments and over-the-phone/mail order. The Cardholder requests to make a payment using the Merchant’s website to send a card-not-present payment. As the website is not the primary method accepted by the Merchant, they can charge a Convenience Fee to the Cardholder.

Begin by following the steps in the Setting up a Fee section under the Using the Portal steps and use the parameters below to complete the process.

Convenience Fee Setup Parameters - Portal

Warning: Convenience Fees can cause legal complications if configured incorrectly or not meeting the general card brand network requirements:

Convenience Fees must be disclosed to customer before completion of a transaction.
You must allow cardholders to cancel the transaction upon reading this disclosure.
Convenience Fees are only allowed for credit and signature debit card types.
Convenience Fees are only allowed for card-not-present transaction types.
Convenience fees cannot be applied to recurring, subscription or installment transactions.

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Capture
How much is the fee?	Actual	Percentage or Surcharge may not be used in any form of Transaction Fee configuration.
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
Transaction Fee	Enabled	Checkbox available under the “Advanced Options” section of the lightbox.

Tip: Use a Fee Rule to only charge Convenience Fees over a specific amount.

Convenience Fee Setup Parameters - API

Warning: Convenience Fees can cause legal complications if configured incorrectly or not meeting the general card brand network requirements:

Convenience Fees must be disclosed to customer before completion of a transaction.
You must allow cardholders to cancel the transaction upon reading this disclosure.
Convenience Fees are only allowed for credit and signature debit card types.
Convenience Fees are only allowed for card-not-present transaction types.
Convenience fees cannot be applied to recurring, subscription or installment transactions.

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`7`	Capture. The Fee triggers at the capture time of a Transaction.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`1`	Enabled as a Transaction Fee
`collection`	`1`
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Tip: Use a Fee Rule to only charge Convenience Fees over a specific amount.

External Fees

External Fees are fees that are assessed from external platforms, such as Visa’s Fixed Acquirer Network Fee (FANF) or MasterCard Merchant Location (MC Location), to a Referrer for the usage of those services. In scenarios where Referrers would like to charge a Merchant to cover the costs of those fees. In some cases, you may want to charge a markup for providing the service through your platform to your Merchants.

Example: A Referrer is enrolled in both MasterCard Merchant Location (MC Location) and Visa Fixed Acquirer Network Fee (FANF) programs for its Merchants to improve interchange rates and reduce fraud. As both of these programs assess Fees to the Referrer based on each individual Merchant’s information (such as number of locations, online-only, etc.) the Referrer would like to charge 100% of the external services’ costs to the Merchant, or could even assess a 102.5% (as an example) for a small markup percentage for enabling the external service.

External Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	{externalService}	Any of the following values are supported as External Fees: FANF - Fixed Acquirer Network Fee from Visa for Merchants processing card-present and card-not-present transactions. MCLocation - Merchant Location Fee from Mastercard for Merchants processing card-present and card-not-present transactions. VisaIntegrity - Transaction Integrity Fee from Visa ValueTec Essential - Essential Gift service for Merchant Gift Card and Rewards programs from Valuetec (paid annually). [Available for select Beta partners.] Valuetec Essential: Monthly - Essential Gift service for Merchant Gift Card and Rewards programs from Valuetec (paid monthly). [Available for select Beta partners.] SaferPayments: Basic - PCI DSS Compliance Portal from WorldPay for Referrer and Facilitator Merchant portfolios. SaferPayments: Managed - PCI DSS Compliance Managed Services from WorldPay for Merchants in Referrer and Facilitator portfolios. SaferPayments - PCI Non-Validation - PCI DSS Compliance Portal and/or services were provided but the Merchant failed to meet PCI DSS Compliance. OmniToken - Omni-Channel payment tokenization from WorldPay
How much is the fee?	Actual	Percentage or Surcharge may not be used in any form of Transaction Fee configuration.
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.

External Fee Setup Parameters - API

External Fees use their own unique endpoint to set up the fee configuration.

Request URL & Header

CODE

POST /externalFees HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

CODE

{
  "entity": "t1_ent_xxxxxxxxxxxx",
  "filename": "string",
  "date": 0,
  "type": "FANF",
  "lineNumber": 0,
  "amount": "string",
  "metadata": []
}

Parameter	Type	Required	Description	Valid Values
`entity`	string	Required	The ID of the Entity the External Fee will be charged to.
`filename`	string	Required	The name of the original WorldPay Ecomm file containing the fee charged by external services.	Max: 100 Characters
`date`	integer	Required	Date when this fee was processed by the external service and charged in the WorldPay Ecomm file.	Format: `YYYYMMDD`
`type`	string	Required	The external service Fee type	`FANF` - FANF. Fixed Acquirer Network Fee from Visa for Merchants processing card-present and card-not-present transactions. `MCLOCATION` - MCLocation. Merchant Location Fee from Mastercard for Merchants processing card-present and card-not-present transactions. `VISAINTEGRITY` - VisaIntegrity. Transaction Integrity Fee from Visa `VALUTEC_ESSENTIAL_GIFT` - ValueTec Essential. Essential Gift service for Merchant Gift Card and Rewards programs from Valuetec (paid annually). [Available for select Beta partners.] `VALUTEC_ESSENTIAL_MONTHLY_TXN` - Valuetec Essential: Monthly. Essential Gift service for Merchant Gift Card and Rewards programs from Valuetec (paid monthly). [Available for select Beta partners.] `SAFERPAYMENTS_BASIC` - SaferPayments: Basic. PCI DSS Compliance Portal from WorldPay for Referrer and Facilitator Merchant portfolios. `SAFERPAYMENTS_MANAGED` - SaferPayments: Managed. PCI DSS Compliance Managed Services from WorldPay for Merchants in Referrer and Facilitator portfolios. `SAFERPAYMENTS_NONVALIDATION` - SaferPayments - PCI Non-Validation. PCI DSS Compliance Portal and/or services were provided but the Merchant failed to meet PCI DSS Compliance. `OMNITOKEN` - OmniToken. Omni-Channel payment tokenization from WorldPay.
`lineNumber`	integer	Required	The `lineNumber` value of the WorldPay Ecomm file associating the external service's fee charge with the newly created External Fee being charged to the Merchant.	Max: 10 Characters
`amount`	string	Required	The numerical fee amount, written in basis points to represent a dollar amount to charge the Merchant.	Format Example: `250` = $2.50
`metadata`	data object	Required	The original Worldpay EComm fee data provided by the external service to the platform to charge the applicable entity (Referrer) the original fee for usage.	Format: JSON only.

CODE

{
      "id": "t1_ext_xxxxxxxxxxxx",
      "entity": "t1_ent_xxxxxxxxxxxx",
      "filename": "FANFFee.ecomm",
      "date": 20231023,
      "type": "FANF",
      "lineNumber": 0,
      "amount": "250",
      "metadata": "string.json",
      "created": "2023-10-25T19:10:44.278Z",
      "modified": "2023-10-25T19:10:44.278Z",
      "creator": "t1_log_xxxxxxxxxxx",
      "modifier": "t1_log_xxxxxxxxxxx"
    }

Parameter	Type	Description	Valid Values
`id`	string	The newly created External Fee ID.
`entity`	string	The ID of the Entity the External Fee will be charged to.
`filename`	string	The name of the original WorldPay Ecomm file containing the fee charged by external services.
`date`	integer	Date when this fee was processed by the external service and charged in the WorldPay Ecomm file.	Format: `YYYYMMDD`
`type`	string	Fee type	`FANF` - FANF. Fixed Acquirer Network Fee from Visa for Merchants processing card-present and card-not-present transactions. `MCLOCATION` - MCLocation. Merchant Location Fee from Mastercard for Merchants processing card-present and card-not-present transactions. `VISAINTEGRITY` - VisaIntegrity. Transaction Integrity Fee from Visa `VALUTEC_ESSENTIAL_GIFT` - ValueTec Essential. Essential Gift service for Merchant Gift Card and Rewards programs from Valuetec (paid annually). [Available for select Beta partners.] `VALUTEC_ESSENTIAL_MONTHLY_TXN` - Valuetec Essential: Monthly. Essential Gift service for Merchant Gift Card and Rewards programs from Valuetec (paid monthly). [Available for select Beta partners.] `SAFERPAYMENTS_BASIC` - SaferPayments: Basic. PCI DSS Compliance Portal from WorldPay for Referrer and Facilitator Merchant portfolios. `SAFERPAYMENTS_MANAGED` - SaferPayments: Managed. PCI DSS Compliance Managed Services from WorldPay for Merchants in Referrer and Facilitator portfolios. `SAFERPAYMENTS_NONVALIDATION` - SaferPayments - PCI Non-Validation. PCI DSS Compliance Portal and/or services were provided but the Merchant failed to meet PCI DSS Compliance. `OMNITOKEN` - OmniToken. Omni-Channel payment tokenization from WorldPay.
`lineNumber`	integer	The `lineNumber` value of the WorldPay Ecomm file associating the external service's fee charge with the newly created External Fee being charged to the Merchant.
`amount`	string	The percentage amount, written in basis points.	Format Example: `300` = 3.00%.
`metadata`	json object	The original Worldpay EComm fee data provided by the external service to the platform to charge the applicable entity (Referrer) the original fee for usage.
`created`	timestamp	The date and time the new External Fee was created.	Format: `YYYY-MM-DDTHH:MM:SS.MS`
`modified`	timestamp	The date and time this External Fee was last modified.	Format: `YYYY-MM-DDTHH:MM:SS.MS`
`creator`	string	The Login ID for the user that created this External Fee
`modifier`	string	The Login ID for the user that last modified this External Fee

Interchange & Processing Fees

If you want to pass along these to your merchants you can set up an Interchange fee schedule at 100% so that they are responsible for covering the fees.

Example: A Referrer would like to pass along the cost of acceptance for debit and credit card interchange to your Merchant.

Interchange & Processing Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Interchange	The Fee triggers based on the interchange type of this Merchant.
How much is the fee?	Percentage
Amount	100.00	The numerical fee amount, written in basis points to represent a percentage.
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.

Tip: Use a Fee Rule to define the Interchange type or specific processor.

Conditional Rules - Debit Network Interchange Fees

In order to properly assess debit network interchange fees, you must configure the following conditional Rule settings under the “Advanced Options” section of the Add Fee modal:

Conditional Rule

Required Value

Note

Payment Card Type is:

Debit

This helps the fee engine differentiate between credit interchange and debit interchange costs.

Payment Card Brand is:

{Debit - [Network]}

Valid Values:

Debit - ACCEL
Debit - ATH
Debit - ARMED FORCES FINANCIAL NETWORK (AFFN)
Debit - CULIANCE (CU24)
Debit - INTERLINK & PAVD
Debit - JEANIE
Debit - MAESTRO
Debit - NYCE
Debit - PULSE
Debit - SHAZAM
Debit - STAR

Interchange & Processing Fee Setup Parameters - API

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`13`	The Fee triggers when interchange default are assessed for the Transactions of this Merchant. You can also create a fee based on the specific type of processor using the Processor option: Processor. The Fee triggers when the Transactions of this Merchant are processed by a payment processor.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`0`	Disabled Transaction Fee
`collection`	`1`
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Tip: Use a Fee Rule to define the Interchange type or specific processor.

Platform Service Fees

This customization allows our partners to seamlessly implement a portfolio-wide or individual new account creation fee to collect from their clients. creating a custom platform service fee in Payrix is an ideal way to automatically bill your clients for your services based on your user agreement with them.

Example: The payment acceptance platform you offer as a Referrer comes at a cost to the Merchant, usually in the form of monthly service plan costs or subscription costs. As the Merchant has agreed to your platform’s terms and conditions, it accepts the costs setup as a Monthly Fee Schedule eliminating the need for a third-party billing solution.

Platform Service Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Months	The Fee triggers every X number of months. You can also use the following Fee Schedules: Days. The Fee is charged every day. Weeks. The Fee is charged every week. Years. The Fee is charged every year. Single. The Fee is a one-time charge.
Every how many monthly?	1	This sets the interval to as recurring once per month. This can also be changed to be bi-monthly (2), quarterly (3), or semi-anually (6) as examples.
How much is the fee?	Actual
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
Fee Name	{yourBusinessName} Platform Service Fee	Optional. This will help more easily identify your Fee when viewing the Portal.

Platform Service Fee Setup Parameters - API

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`3`	Months. The Fee is charged every month. You can also use the following Fee Schedules: `1` - Days. The Fee is charged every day. `2` - Weeks. The Fee is charged every week. `4` - Years. The Fee is charged every year. `5` - Single. The Fee is a one-time charge.
`scheduleFactor`	`1`	This sets the interval to as recurring once per month. This can also be changed to be bi-monthly (`2`), quarterly (`3`), or semi-annually (`6`) as examples.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`0`	Disabled Transaction Fee
`collection`	`3`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Risk Decision Fees

Risk Decision Fees allow you to charge fees to a Merchant when core platform risk services are used to evaluate when a risk decision is made for a boarding Merchant or when a processed Transaction has risk checks performed to ensure compliance.

Example: A Referrer would like to charge a Merchant when the platform risk service performs an automated transaction check. This happens when specific risk criteria are met and delay the disbursement of transaction funds in addition to fraud and risk compliance concerns. As a result, the Referrer will charge a fee when these events occur to actively discourage the Merchant from high-risk transaction actions and behaviors

Risk Decision Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Internal Decision V2	Payrix automated Risk decision services. You can also use the following options for different supported Risk Services: Valid Values: `25` - Misuse. The Fee triggers when a txn authorization is misused. `28` - Disbursement NOC. The Fee triggers on Notice Of Change events for Disbursements. `29` - Transaction NOC. The Fee triggers on Notice Of Change events for Transactions. `70` - Boarding Decision - Merchant boarding decision made by the platform via risk checks. `71` - Transaction Risk Decision - Transaction decision made by the platform via risk checks.
How much is the fee?	Actual
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
Fee Name	{yourBusinessName} Risk Decision Service Fee	Optional. This will help more easily identify your Fee when viewing the Portal.

Tip: Use Fee Rules to refine the specific risk decision status or additional misuse criteria.

Risk Decision Fee Setup Parameters - API

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`62`	Internal Decision V2. Payrix automated risk decision services. You can also use the following Risk Decision schedules: `25` - Misuse. The Fee triggers when a txn authorization is misused. `28` - Disbursement NOC. The Fee triggers on Notice Of Change events for Disbursements. `29` - Transaction NOC. The Fee triggers on Notice Of Change events for Transactions. `70` - Boarding Decision - Merchant boarding decision made by the platform via risk checks. `71` - Transaction Risk Decision - Transaction decision made by the platform via risk checks.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`0`	Disabled Transaction Fee
`collection`	`3`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Tip: Use Fee Rules to refine the specific risk decision status or additional misuse criteria.

Risk Service Fees

Risk Service Fees allow you to charge additional fees for the use of integrated third-party risk service. This flexibility enables Referrers to assess fees to Merchants that are higher risk requiring manual validations of the entity and its transactions on a regular basis in addition to fees assessed from the given risk service(s).

Example: A Referrer would like to assess fees to their Merchants to cover the costs of external risk services they use to ensure their Merchants' compliance. These services could include OFAC checks, personal credit pulls, or other necessary risk items needed for boarding or ongoing risk reviews.

Risk Service Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Internal Decision V2	Payrix automated Risk decision services. You can also use the following options for different supported Risk Services: Sift - Real-time machine learning risk prediction systems behavior patterns identity. Realtime Business Search - Real-time Business Entity OFAC Search from Bridger by LexisNexis. Realtime Member Search - Real-time Business Entity Managing Member Personal OFAC Search from Bridger by LexisNexis. MasterCard MATCH - Merchant History Check from Mastercard Alert To Control High-risk Merchants (MATCH) program. Business Instant ID - KYB Verification from LexisNexis. Consumer Instance ID - KYC Verification from LexisNexis. ThreatMetrix - Black List & OFAC Watchlist check from LexisNexis LegitScript - Merchant Compliance and Risk Rating Checks. Equifax Consumer Report - Business owner's consumer credit report from Equifax. CharityCheck - Business entity nonprofit eligibility verification from GuideStar. TIN Check - Tax Identification Number matching service for tax identity management from Sovos. GIACT eCheck Verification - Real-time account status check for consumer and business bank accounts from gVerify by GIACT. GIACT Account Verification - Real-time Business Entity Owner identity & authorized signer status verification from gAuthenticate by GIACT.
How much is the fee?	Percentage
Amount	100%	The numerical fee percentage amount, written in basis points (Example: `10000` = 100%). Note: You can create a markup on this fee by going above 100% such as 103.5% (written as `10350`)
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.

Risk Service Fee Setup - API

Add Fee Parameter	Required Value	Note
`type`	`2`	Fee. A Standard Fee.
`schedule`	`53`	Realtime Business Search. Real-time Business Entity OFAC Search from Bridger by LexisNexis. You can also use the following Risk Services: `54` - Realtime Member Search. Real-time Business Entity Managing Member Personal OFAC Search from Bridger by LexisNexis. `55` - MasterCard MATCH. Merchant History Check from Mastercard Alert To Control High-risk Merchants (MATCH) program. `56` - Business Instant ID. KYB Verification from LexisNexis `57` - Consumer Instance ID. KYC Verification from LexisNexis. `58` - ThreatMetrix. Black List & OFAC Watchlist check from LexisNexis `59` - LegitScript Registration. Merchant Compliance and Risk Rating Checks. `60` - Equifax Consumer Report. Business owner's consumer credit report from Equifax. `61` - CharityCheck. Business entity nonprofit eligibility verification from GuideStar. `63` - TIN Check. Tax Identification Number matching service for tax identity management from Sovos. `64` - Equifax Commercial Report. Entity's commercial credit report from Equifax. `65` - LegitScript Merchant Check. Merchant Compliance and Risk Rating Checks. `66` - Plaid. Bank account link, info update and verification services. `68` - GIACT eCheck Verification. Real-time account status check for consumer and business bank accounts from gVerify by GIACT. `69` - GIACT Account Verification. Real-time Business Entity Owner identity & authorized signer status verification from gAuthenticate by GIACT.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`0`	Disabled Transaction Fee
`collection`	`3`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Surcharge Fees

Surcharging allows Referrers to charge a per-transaction fee each time a credit card is used by cardholder that is charged to the Merchant but can be passed to the cardholder directly.

Example: The payment acceptance platform you offer as a Referrer assesses a 3% surcharge to Merchants for processing credit-only transactions to offset associated processing fees. As a result, you enable each of your Merchants to collect this surcharge from their customers using credit cards.

Warning: There are individual registration requirements and regulations by card brand before you can enable surcharges. The following steps will demonstrate how to enable the Surcharge once all prerequisits are met. Visit Understanding Surcharges for more details on the enablement requirements.

Warning: Surcharging is still illegal in a few US states/territories: Connecticut, Massachusetts, and Puerto Rico. Be sure to follow your local and regional regulations accordingly.

Surcharge Fee Setup Parameters - Portal

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Capture	The Fee is triggered at the time of credit card capture for a transaction.
How much is the fee?	Surcharge
Amount	3%	The numerical fee amount, written in basis points to represent a percentage. (Example: `300` = 3.00%). Warning: When setting up a surcharge, do not exceed 3% to adhere with all credit card brand regulations.
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
Transaction Fee	Enabled	Checkbox available under the “Advanced Options” section of the lightbox.
Conditional Rule	Payment Card Type is	Credit Warning: This is required when setting up a surcharge as credit cards are the only payment method that allow surcharging.

Surcharge Fee Setup Parameters - API

Surcharge fees require a two-part fee setup involving the creation of a fee and a fee rule:

Setting up the Surcharge Fee
Enabling the Credit-Only Fee Rule (required by card brands)

This model follows industry-standard rates and regulations as presented by card brands fees: 3% surcharging on credit card transaction only.

Part 1: Setup the initial Surcharge Fee.

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`7`	Capture. The Fee is triggered at the time of credit card capture for a transaction.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`3`	Surcharge. The Fee is a percentage, specified in the `amount` field in basis points.
`amount`	`300`	The numerical fee amount, written in basis points to represent a percentage. (Example: `300` = 3.00%). Warning: When setting up a surcharge, do not exceed 3% to adhere with all credit card brand regulations.
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars.
`txnFee`	`1`	Enabled Transaction Fee
`collection`	`1`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Part 2: Apply a Credit-Only Surcharge Fee Rule.

Fee Rules utilize a different endpoint, see the information below:

Request URL & Header

CODE

POST /feeRules HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

JSON

{
  "fee": "t1_fee_xxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Credit-Only Surcharge Rule",
  "description": "Only allows surcharging on credit cards.",
  "type": "methodType",
  "application": "both",
  "value": "credit",
  "inactive": "0",
  "frozen": "0"
}

Parameter	Type	Required	Description	Valid Values
`fee`	string	Required	The ID of the Fee you created in Step 1 shown in the response body for `POST /fees`.	Format: `t1_fee_x...`
`name`	string	Optional	Custom name for the Fee Rule to make it easy to find.	Recommended name: `Credit-Only Surcharge Rule`
`description`	string	Optional	Custom description for the Fee Rule to summarize it’s purpose.	Recommended name: `Only allows surcharging on credit cards.`
`type`	string	Required	The type of Fee Rule deciding the `value` parameter.	`methodType` This is selecting the payment method/card type, required for this fee setup.
`application`	string	Required	When the Fee Rule is applied.	`both` The rule should apply to the fee and to the calculation of collections.
`value`	string	Required	The value of deciding the Fee Rule condition set originally in the `type` parameter.	`credit` This is selecting the credit cards only as the payment method/card type that will be applied in the surcharge, required for this fee setup.
`inactive`	integer	Required	Whether or not this fee is active.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Required	Whether or not this fee is temporarily frozen.	Valid Values: `0` - Not frozen `1` - Frozen

CODE

{
      "id": "t1_frl_xxxxxxxxxxxxxxxxxxxxxxx",
      "created": "2024-01-24T17:50:38.717Z",
      "modified": "2024-01-24T17:50:38.717Z",
      "creator": "t1_log_xxxxxxxxxxxxxxxxxxxxxxx",
      "modifier": "t1_log_xxxxxxxxxxxxxxxxxxxxxxx",
      "fee": "t1_fee_xxxxxxxxxxxxxxxxxxxxxxx",
      "name": "Credit-Only Surcharge Rule",
      "description": "Only allows surcharging on credit cards.",
      "type": "methodType",
      "application": "both",
      "value": "credit",
      "inactive": "0",
      "frozen": "0",
    }

Parameter	Type	Description	Valid Values
`id`	string	The newly created Fee Rule ID.	Format: `t1_frl_x...`
`created`	timestamp	The date and time the new Fee Rule was created.	Format: `YYYY-MM-DDTHH:MM:SS.MS`
`modified`	timestamp	The date and time this Fee Rule was last modified.	Format: `YYYY-MM-DDTHH:MM:SS.MS`
`creator`	string	The Login ID for the user that created this Fee Rule	Format: `t1_log_x...`
`modifier`	string	The Login ID for the user that last modified this Fee Rule	Format: `t1_log_x...`
`fee`	string	The ID of the Fee your new Fee rule will be applied to.	Format: `t1_fee_x...`
`name`	string	Custom name for the Fee Rule to make it easy to find.	Recommended name: `Credit-Only Surcharge Rule`
`description`	string	Custom description for the Fee Rule to summarize it’s purpose.	Recommended description: `Only allows surcharging on credit cards.`
`type`	string	The type of Fee Rule deciding the `value` parameter.	`methodType` This is selecting the payment method/card type, required for this fee setup.
`application`	string	When the Fee Rule is applied.	`both` The rule should apply to the fee and to the calculation of collections.
`value`	string	The value of deciding the Fee Rule condition set originally in the `type` parameter.	`credit` This is selecting the credit cards only as the payment method/card type that will be applied in the surcharge, required for this fee setup.
`inactive`	integer	Whether or not this fee is active.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Whether or not this fee is temporarily frozen.	Valid Values: `0` - Not frozen `1` - Frozen

Transaction Fees

Transaction Fees allow Referrers to charge their Merchants on a per-transaction basis to generate revenue as a Referrer.

Example: The payment acceptance platform you offer as a Referrer charges a per-transaction fee in the form of a flat rate authorization fee and a captured amount percentage. This is a common Fee model in the Payments industry commonly seen as “Transaction Processing Fees: 10¢ + 3%” for example.

Transaction Fee Setup Parameters - Portal

This Transaction fee will use a two-part fee setup that involves the creation of multiple fees.

Setting up a flat rate fee for all credit card Authorizations.
Setting up a percentage fee for credit card Captures.

This model most closely resembles industry-standard payment processing fees: Flat Fee + % of the transaction total.

Part 1: Setting up a flat rate Authorization Fee.

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Auth	The Fee is triggered at the time of authorization of a transaction. You can also use the following Fee Schedules: Refund. The Fee triggers when a refund transaction is processed.
How much is the fee?	Actual
Amount	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `015` = $0.15). Warning: Refer to each card brand and processor’s policies on Transaction fees to ensure compliance.
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
Transaction Fee	Enabled	Checkbox available under the “Advanced Options” section of the lightbox.

Part 2: Setting up a Capture Fee for a percentage of the transaction total.

Add Fee Parameter	Required Value	Note
When to trigger the fee?	Capture	The Fee triggers at the capture time of a Transaction.
How much is the fee?	Percentage
Amount	{yourFeeAmount}	The percentage amount, written in basis points. (Example: `300` = 3.00%). Warning: Refer to each card brand and processor’s policies on Transaction fees to ensure compliance.
Fee Start Date	{yourStartDate}	It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
Transaction Fee	Enabled	Checkbox available under the “Advanced Options” section of the lightbox.

Tip: Use Fee Rules to define the specific method of payment acceptance can trigger the Fee.

Transaction Fee Setup Parameters - API

This Transaction fee will use a two-part fee setup that involves the creation of multiple fees.

Setting up a flat rate fee for all credit card Authorizations.
Setting up a percentage fee for credit card Captures.

This model most closely resembles industry-standard payment processing fees: Flat Fee + % of the transaction total.

Part 1: Setting up a flat rate Authorization Fee.

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`6`	Auth. The Fee is triggered at the time of authorization of a transaction. You can also use the following Fee Schedules: `8` - Refund. The Fee triggers when a refund transaction is processed.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`2`	Fixed Amount. The Fee is a fixed amount, specified in the 'amount' field as an integer in cents. This is called “Actual” in the Portal Add Fee lightbox.
`amount`	{yourFeeAmount}	The numerical fee amount, written in basis points to represent a dollar amount (Example: `250` = $2.50).
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`1`	Enabled Transaction Fee
`collection`	`1`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Part 2: Setting up a Capture Fee for a percentage of the transaction total.

Add Fee Parameter	Required Value	Note
`type`	`1`	Fee. A Standard Fee.
`schedule`	`7`	Capture. The Fee triggers at the capture time of a Transaction.
`scheduleFactor`	`0`	No schedule factor is needed (`0`) as this is event-based.
`um`	`1`	Percentage. The Fee is a percentage of the related event amount, specified in the 'amount' field in basis points.
`amount`	{yourFeeAmount}	The percentage amount, written in basis points. (Example: `300` = 3.00%). Warning: Refer to each card brand and processor’s policies on Transaction fees to ensure compliance.
`start`	{yourStartDate}	`YYYYMMDD` Format. It is recommended to use “today’s” date as the Fee Start Date to make the Fee effective immediately.
`currency`	`USD`	US Dollars. CAD is also accepted.
`txnFee`	`1`	Enabled Transaction Fee
`collection`	`1`	Txn-Merchant. The total amount of all transactions per entity.
`collectionFactor`	`0`	No Collection Factor
`collectionOffset`	`0`	No Collection Offset
`inactive`	`0`	Active
`frozen`	`0`	Not Frozen

Tip: Use Fee Rules to define the specific method of payment acceptance can trigger the Fee.

Adding Fee Modifiers

To change the entity that will be paying the cost for the Fee charge, you’ll need to setup a Fee Modifier.

Using the Portal

Click here for steps to set up a Fee Modifier while creating a new Fee.

Warning: This process will not work if you have not setup a new Fee or are selecting an existing Fee configuration. Please see Setting up a Fee above for steps to setup a Fee if you’re not using an existing Fee setup.

After you’ve configured you’re initial Fee Type, to add additional Fee Rules, follow the steps below:

Step 1: Click Advanced Options in the Add Fee lightbox after your initial Fee setup.
Step 2: Check the “Deduct this Fee from Another Entity” checkbox, then under the DEDUCT FEE FROM drop-down, select the entity that the fee charge will be paid by.

Result: Finish configuring the rest of your Advanced Options for your fee and click the ADD button when finished to save the new Fee Modifier within the new Fee.

Click here for steps to setup a Fee Modifier on an existing Fee.

Step 1: Navigate to the Merchants or Groups page, located under Management.
Step 2: Click the Merchant or Group you want to charge the Fee to enter its Merchant Profile or Group Profile page.
Step 3: In the Merchant Profile or Group Profile, click Fees from the left-hand menu. Then, click the Fee setup you’d like to add the Fee Rule to from the Active Fees Section to enter the Fee Details page.
Step 4: On the Fees Details page, click the dropdown under the Fee Modifiers section and click the Add Fee Modifier button in the upper-right of the section.
Step 5: Set the the unit of measurement, amount, group (if applicable) and the ID for the “From Entity” (the entity that will be paying the fee) in the new field that has appeared.

Result: Click the ADD button when finished to save the new Fee Modifier to the existingFee.

Using the API

Request URL & Headers

CODE

POST /feeModifiers HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

Request Body Example - Apply Fee Modifier for Entity #2 to Pay the Fee with a 10% markup.

CODE

{
  "fee": "t1_fee_xxxxxxxxxxxx",
  "entity": "t1_ent_1xxxxxxxxxxx",
  "org": "t1_org_xxxxxxxxxxxx",
  "fromentity": "t1_ent_2xxxxxxxxxxx",
  "markupUm": 2,
  "markupAmount": "1000",
  "inactive": "0",
  "frozen": "0"
}

Request Body Parameters - Fee Modifiers

Parameter	Type	Required	Descriptions	Valid Values
`fee`	string	Required	The Fee ID for the Fee you want to apply the Fee Modifier to.
`entity`	string	Optional	The Entity ID for the Entity you want to apply the Fee Modifier to.
`org`	string	Optional	The Org ID for the Org (Group) that you want to apply the Fee Modifier to.
`fromentity`	string	Required	The Entity ID for the Entity that will now be paying the cost of the original fee charges, with potential markup, on behalf of the specified Entity or Org above.
`markupUm`	integer	Optional	The unit of measurement for an optional markup amount.	Valid Values: `1` - Fixed Amount. Specified in the 'markupAmount' field as an integer in cents. `2` - Percentage Specified in the 'markupAmount' field in basis points.
`markupAmount`	number	Optional	The total amount of the markup value for this Fee. The units used in this field are determined by the value of the 'markupUm' field on the Fee. If the 'markupUm' field is set to 'percentage', then this field specifies the Fee percentage to levy in basis points. If the 'markupUm' field is set to 'actual', then this field specifies the markup amount in cents.	Formatting Examples: Fixed Amount `1000` = $10.00 Percentage `1000` = 10.00%
`inactive`	integer	Required	Whether or not this Fee Modifier is inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Required	Whether or not this Fee Modifier has been frozen.	Valid Values: `0` - Not frozen `1` - Frozen

Response Body Example - - Apply Fee Modifier for Entity #2 to Pay the Fee with a 10% markup.

CODE

{
  "id": "t1_fmr_xxxxxxxxxxxx",
  "created": "2023-12-01T14:21:33.355Z",
  "modified": "2023-12-01T14:21:33.355Z",
  "creator": "t1_log_xxxxxxxxxxxx",
  "modifier": "t1_log_xxxxxxxxxxxx",
  "fee": "t1_fee_xxxxxxxxxxxx",
  "entity": "t1_ent_1xxxxxxxxxxx",
  "org": "t1_org_xxxxxxxxxxxx",
  "division": "t1_div_xxxxxxxxxxxx",
  "fromentity": "t1_ent_2xxxxxxxxxxx",
  "markupUm": "2",
  "markupAmount": "1000",
  "inactive": "0",
  "frozen": "0"
}

Response Body Parameters - Fee Modifiers

Parameter	Type	Description	Valid Values
`id`	string	The ID of the newly created Fee Modifier.
`created`	string	The Date and Time that the Fee Modifier was created.
`modified`	string	The Date and Time that the Fee Modifier was last modified.
`creator`	string	The Login ID for the user that created the Fee Modifier.
`modifier`	string	The Login ID for the user that last modified the Fee Modifier.
`fee`	string	The Fee ID for the Fee you want to apply the Fee Modifier to.
`entity`	string	The Entity ID for the Entity you want to apply the Fee Modifier to.
`org`	string	The Org ID for the Org (Group) that you want to apply the Fee Modifier to.
`division`	string	The division containing the group or entities associated with the configuration.
`fromentity`	string	The Entity ID for the Entity that will now be paying the cost of the original fee charges, with potential markup, on behalf of the specified Entity or Org above.
`markupUm`	integer	The unit of measurement for an optional markup amount.	Valid Values: `1` - Fixed Amount. Specified in the 'markupAmount' field as an integer in cents. `2` - Percentage Specified in the 'markupAmount' field in basis points.
`markupAmount`	number	The total amount of the markup value for this Fee. The units used in this field are determined by the value of the 'markupUm' field on the Fee. If the 'markupUm' field is set to 'percentage', then this field specifies the Fee percentage to levy in basis points. If the 'markupUm' field is set to 'actual', then this field specifies the markup amount in cents.	Formatting Examples: Fixed Amount `1000` = $10.00 Percentage `1000` = 10.00%
`inactive`	integer	Whether or not this Fee Modifier is inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Whether or not this Fee Modifier has been frozen.	Valid Values: `0` - Not frozen `1` - Frozen

Adding Fee Rules

To configure and refine the criteria of the Fee Schedule or “When to trigger the fee?” selection of a fee you’ve just created, follow the steps below.

Using the Portal

Click here for steps to set up a Fee Rule while adding a new Fee.

Warning: This process will not work if you have not setup a new Fee or are selecting an existing Fee configuration. Please see Setting up a Fee above for steps to setup a Fee if you’re not using an existing Fee setup.

After you’ve configured you’re initial Fee Type, to add additional Fee Rules, follow the steps below:

Step 1: Click Advanced Options in the Add Fee lightbox after your initial Fee setup.

Step 2: Click Conditional Rules and select a Fee Rule option. See Fee Rules for a list of available options with descriptions.

Step 3: Set the amount or value in the new field that has appeared.

Step 4: (Optional) After setting up your first Fee Rule, you can click the + button next to your first rule to add another.

Note: If you’d like to remove a rule from the Conditional Rules section as you’re setting up a Fee Rule, click the Trash Can icon next to the rule you wish to delete.

Click the ADD button when finished to save the new Fee Rule(s).

Click here for steps to setup a Fee Rule on an existing Fee.

Step 1: Navigate to the Merchants or Groups page, located under Management.

Step 2: Click the Merchant or Group you want to charge the Fee to enter its Merchant Profile or Group Profile page.

Step 3: In the Merchant Profile or Group Profile, click Fees from the left-hand menu. Then, click the Fee setup you’d like to add the Fee Rule to from the Active Fees Section to enter the Fee Details page.

Step 4: On the Fees Details page, click the dropdown under the Fee Rules section and select a Fee Rule option. See Fee Rules for a list of available options with descriptions.

Step 5: Set the amount or value in the new field that has appeared.

Step 6: (Optional) After setting up your first Fee Rule, you can click the + button next to your first rule to add another.

Note: If you’d like to remove a rule from the Conditional Rules section as you’re setting up a Fee Rule, click the Trash Can icon next to the rule you wish to delete.

Click the Checkmark button in the upper right to save the new Fee Rule(s).

Using the API

Request URL & Headers

CODE

POST /feeRules HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

Request Body Example - Fee Rule: Do not apply the Fee to Transcations with totals under $100.

JSON

{
  "fee": "t1_fee_xxxxxxxxxxxxxxxxxxx",
  "name": "No Fee for Txns < $l00",
  "description": "This fee rule applies to Convenience Fees and will only apply the Fee when the total transaction amount is over $100.",
  "type": "less",
  "application": "both",
  "value": "10000",
  "grouping": "0",
  "inactive": "0",
  "frozen": "0",
}

Request Body Parameters - Fee Rules

Parameter	Type	Required	Descriptions	Valid Values
fee	string	Required	The Fee ID for the Fee you want to apply the Fee Rule to.
name	string	Optional	Custom name for the Fee Rule for easy identification.
description	string	Optional	Custom description for the Fee Rule for clarification.
type	string	Required	The type of rule you’ll be applying to the specified Fee.	`less` - Less than. The Fee applies only if the triggered amount is lower than the amount set in the 'value' field of the Fee Rule. `equal`- Equal to. The Fee applies only if the transaction amount is exactly the same as the amount set in the 'value' field of the Fee Rule. `notEqual` - Not equal to. The Fee applies only if the transaction amount is not exactly equal to the amount set in the 'value' field of the Fee Rule. `greater` - Greater than. The Fee applies only if the transaction amount is higher than the amount set in the 'value' field of the Fee Rule. `swiped` - Swiped. The Fee applies based on a determination of whether the cardholder was present during the transaction. `signed` - Signed. The Fee applies based on a determination of whether the cardholder added a signature to the transaction or not. `type` - Type. The Fee applies based on the type of transaction. `origin` - Origin. The Fee applies based on the origin of a transaction. `method` - Method. The Fee applies based on method of payment. `interchange` - Interchange. The Fee applies based on a specific interchange type. `cvvResult` - CVV Result. The Fee applies based on the results of a CVV check. `avsResult` - AVS Result. The Fee applies based on the results of an AVS check. `3dsResult` - 3DS Result. The Fee applies based on the results of a 3DS check. `mcc` - MCC. The Fee applies only to merchants with the given MCC. `merchantCountry` - Merchant country. The Fee applies only to merchants from the given country. `issuerCountry` - Issuer country. The Fee applies only to transactions where the credit card used was issued in the given country. `international` - International. The Fee applies based on the payment method being international or domestic, depending on the value set. `platform` - Platform. The Fee applies only to transactions processed through the given platform. `methodType` - Method type. The Fee applies based on the given payment method. `emv` - EMV. The Fee applies only to transactions processed using an EMV chip. `misuse` - Misuse. The Fee applies only to either misused or not misused transactions. `bin` - Bin. The Fee applies only to transactions where the payment method matches the given bin number. `fundingCurrencyEqual` - Funding Currency. The Fee applies only to transactions where the funding currencys equals the given currency. `fundingCurrencyNotEqual` - Funding Currency. The Fee applies only to transactions where the funding currencys does not equal the given currency. `fundingCurrencyMismatch` - Funding Currency. The Fee applies only to transactions where the funding currency and purchase currency does not match. `fundingEnabled` - Funding Enabled. The Fee applies only to transactions with the given fundingCurrency value. `settledCurrencyMismatch` - Funding Currency. The Fee applies only to transactions where the funding currency and settled currency does not match. `status` - Txn Status. The Fee applies based on the txn status.
application	string	Required	When this Fee Rule will be applied.	`both` - Both. The rule should apply to the fee and to the calculation of collections. `fee` - Fee. The rule should apply only to the fee itself. `collection` - Collection. The fee should be only used when calculating a collection.
value	string	Required	This field refers to either the numerical amount for `type` parameter selections that require an amount. This field can also use a set of valid, non-numerical values that specify the Fee Rule value that triggers the type. The following Fee Types are applicable: `swiped` `signed` `type` `origin` `method` `interchange` `cvvResult` `avsResult` `3dsResult` `merchantCountry` `issuerCountry` `international` `platform` `methodType` `emv` `misuse` `fundingCurrencyMismatch` `fundingEnabled` `settledCurrencyMismatch` `status` Note: `mcc` & `bin` value parameters are technically numerically formatted values but each have specific valid values that cannot be covered comprehensively here. See the `mcc` & `bin` sections of the Valid Values column for more information.	The following `type` parameters use a `true` or `false` value to specify whether or not the specific action or event occured: `swiped` - Card was swiped. `signed` - Cardholder signature captured. `related` - Related to another transaction. `entity` - `international`- Transaction is international `emv` - Card was “dipped” (chip inserted). `misuse` - Misuse was detected. `fundingCurrencyMismatch` - The funding currency type does not match the transaction currency. `fundingEnabled`- Funding currency was specified for the transaction. `settledCurrencyMismatch` - The settled currency type does not match the transaction currency. `imported` - The transaction was imported from another platform. `sameDay` - A same-day withdrawal payout of a transaction’s funds to the Merchant occured. See the remaining `value` valid values by `type`: `type` Valid Values: `auth` - Credit Card Only: Auth Transaction. Authorizes and holds the requested total on the credit card. `unauth` - Credit Card Only: Reverse Authorization. Reverses a prior Auth or Sale Transaction and releases the credit hold. `sale` - Credit Card Only: Sale Transaction. Processes a sale and charges the customer. `refund` - Credit Card Only: Refund Transaction. Refunds a prior Capture or Sale Transaction (total may be specified for a partial refund). `capture` - Credit Card Only: Capture Transaction. Finalizes a prior Auth Transaction and charges the customer. `ecsale` - eCheck Only: eCheck Sale Transaction. Sale Transaction for eCheck payment. `ecrefund` - eCheck Only: eCheck Refund Transaction. Refund Transaction for prior eCheck Sale Transaction. `ecredeposit` - eCheck Only: eCheck Redeposit Transaction. Attempt to redeposit a prior failed eCheck Sale Transaction. `ecverify` - eCheck Only: eCheck Account Verification Transaction. Attempt to verify eCheck payment details. `origin` Valid Values: `terminal` - Originated at a credit card terminal. `ecommerce` - Originated through an eCommerce system. `moto` - Originated as a mail order or telephone order transaction. `applePay` - Originated with Apple Pay. `3dsAuth` - Originated as a Successful 3D Secure transaction. `3dsAtt` - Originated as an Attempted 3D Secure transaction. `subscription` - Originated as a recurring transaction on the card. `payFrame` - Originated in a PayFrame. `method` Valid Values: `amex` - American Express `visa` - Visa `mc` - MasterCard `diners` - Diner's Club `discover` - Discover `paypal` - PayPal `debit` - Debit Card `checking` - Checking Account `savings` - Savings Account `giftCard` - Gift Card `ebt` - Electronic Benefits Transfer Card `wic` - Women Infants and Children Card `methodType` Valid Values: `credit` - Credit Card `debit` - Debit Card `debitCredit` - Debit & Credit Card `charge` - Charge Card `prepaid` - Prepaid Card `bankAccount` - ACH Payment `platform` Valid Values: `apple` - Apple processor `elavon` - Elavon processor `fedach` - The U.S. Federal ACH system `firstdata` - First Data processor `payrix` - Payrix mobile `tdbank` - TD Bank ACH funding service `tdbankca` - TD Bank Canadian EFT funding service `vantiv` - The WorldPay (aka Vantiv or Litle) eComm (aka VAP) processor `wellsach` - Wells Fargo ACH funding service. `wellsfargo` - Wells Fargo Merchant Services processor `wfsingle` - Wells Fargo single processor `interchange` Valid Values: `flatRate` - Merchants are charged a fixed percentage fee and a fixed transaction fee for each transaction. `costPlus` - Also known as Interchange Plus, Merchants are charged two separate fees: the interchange fee and the markup. `tiered` - Merchants are charged a varying surcharge based on Risk level. `cvvResult` Valid Values: `match` - The CVV matches the cardholder info. `noMatch` - The CVV does not match the cardholder info. `unavailable` - The CVV verification service is unavailable. `avsResult` Valid Values: `match` - The Address Verification Service (AVS) matched the Cardholder data. `noMatch` - The AVS found no matches for any Cardholder data. `zipNoMatch` - The AVS found no matching zip/postal code. `addressNoMatch` - The AVS found no matches for the Cardholder Address. `nameNoMatch` - The AVS found no matches for the Cardholder name at the associated address. `namePhoneNoMatch` - The AVS found no match for Cardholder name or phone number. `emailNoMatch` - The AVS found no match for Cardholder email address. `phoneNoMatch` - The AVS found no match for Cardholder phone number. `phoneEmailNoMatch` - The AVS found no match for Cardholder phone number or email address. `nameUnavailable` - The AVS name verification service is unavailable. `namePhoneUnavailable` - The AVS name and phone number verification services are unavailable. `nameEmailUnavailable` - The AVS name and email address verification services are unavailable. `phoneUnavailable` - The AVS phone number verification service is unavailable. `phoneEmailUnavailable` - The AVS phone number and email address verification services are unavailable. `emailUnavailable` - The AVS email address verification service is unavailable. `unavailable` - All AVS verification services are unavailable. `3dsResult` Valid Values: `3dsAuthenticationSuccessful` - The 3DS transaction authentication was successful. `3dsAuthenticationNotValid`ated - The 3DS transaction authentication could not be validated. `3dsAuthenticationFailed` - The transaction failed 3DS authentication. `3dsAuthenticationInvalid` - The transaction data provided for 3DS authentication was incomplete or malformed. `3dsAuthenticationSuccessfulWithoutLiabilityShift` - The 3DS transaction authentication was successful but transaction fraud liability will remain with the Merchant in the case of a future chargeback. `merchantCountry` Format Format: 3-digit Alpha-3 country ISO code. Examples: `USA` - The United States `CAN` - Canada `issuerCountry` Format Format: 3-digit Alpha-3 country ISO code. Examples: `USA` - The United States `CAN` - Canada `status` Valid Values: `pending` - Transaction is pending, has not yet been sent to the processor `approved` - Transaction is approved `failed` - Transaction has failed, either declined through the processor or failed processing internally `captured` - Transaction has been settled to the processor (captured) `settled` - Transaction funds have been settled from the issuer to the processor (settled) `returned` - For eCheck transactions: the transaction has been returned by the receiver `bin` - The Bank Issuer Number for the card used in the transaction following the Issuer's formatting. Tip: You can find this by making a request to the `GET /bins` endpoint. `mcc` - The 4-digit Merchant Category code following the ISO 18245 classification.
grouping	integer	Optional	Determines which rule will be chosen between two or more rule configurations. The “or” logic will decide how to refine the Fee Schedule between two or more rules based on the criteria of the rule met first. The “and” logic will apply all rules to refine the Fee Schedule.	Valid Values: `0` - Use "or" multi-Fee Rule single-choice logic. `1` - Use "and" multi-Fee Rule combination logic.
inactive	integer	Required	Whether or not this Fee Rule is inactive.	Valid Values: `0` - Active `1` - Inactive
frozen	integer	Required	Whether or not this Fee Rule has been frozen.	Valid Values: `0` - Not frozen `1` - Frozen

Response Body Example - Fee Rule: Do not apply the Fee to Transcations with totals under $100.

CODE

{
      "id": "t1_rul_xxxxxxxxxxxxxxxxxxx",
      "created": "2023-10-25T19:10:44.278Z",
      "modified": "2023-10-25T19:10:44.278Z",
      "creator": "t1_log_xxxxxxxxxxxxxxxxxxx",
      "modifier": "t1_log_xxxxxxxxxxxxxxxxxxx",
      "fee": "t1_fee_xxxxxxxxxxxxxxxxxxx",
      "name": "No Fee for Txns < $l00",
      "description": "This fee rule applies to Convenience Fees and will only apply the Fee when the total transaction amount is over $100.",
      "type": "less",
      "application": "both",
      "value": "100000",
      "grouping": "0",
      "inactive": "0",
      "frozen": "0",
    }

Response Body Parameters - Fee Rules

Parameter	Type	Description	Valid Values
`id`	string	The ID of the newly created Fee Rule.
`created`	string	The Date and Time that the Fee Rule was created.
`modified`	string	The Date and Time that the Fee Rule was last modified.
`creator`	string	The Login ID for the user that created the Fee Rule.
`modifier`	string	The Login ID for the user that last modified the Fee Rule.
`name`	string	Custom name for the Fee Rule for easy identification.
`description`	string	Custom description for the Fee Rule for clarification.
`type`	string	The type of rule you’ll be applying to the specified Fee.	`less` - Less than. The Fee applies only if the triggered amount is lower than the amount set in the 'value' field of the Fee Rule. `equal`- Equal to. The Fee applies only if the transaction amount is exactly the same as the amount set in the 'value' field of the Fee Rule. `notEqual` - Not equal to. The Fee applies only if the transaction amount is not exactly equal to the amount set in the 'value' field of the Fee Rule. `greater` - Greater than. The Fee applies only if the transaction amount is higher than the amount set in the 'value' field of the Fee Rule. `swiped` - Swiped. The Fee applies based on a determination of whether the cardholder was present during the transaction. `signed` - Signed. The Fee applies based on a determination of whether the cardholder added a signature to the transaction or not. `type` - Type. The Fee applies based on the type of transaction. `origin` - Origin. The Fee applies based on the origin of a transaction. `method` - Method. The Fee applies based on method of payment. `interchange` - Interchange. The Fee applies based on a specific interchange type. `cvvResult` - CVV Result. The Fee applies based on the results of a CVV check. `avsResult` - AVS Result. The Fee applies based on the results of an AVS check. `3dsResult` - 3DS Result. The Fee applies based on the results of a 3DS check. `mcc` - MCC. The Fee applies only to merchants with the given MCC. `merchantCountry` - Merchant country. The Fee applies only to merchants from the given country. `issuerCountry` - Issuer country. The Fee applies only to transactions where the credit card used was issued in the given country. `international` - International. The Fee applies based on the payment method being international or domestic, depending on the value set. `platform` - Platform. The Fee applies only to transactions processed through the given platform. `methodType` - Method type. The Fee applies based on the given payment method. `emv` - EMV. The Fee applies only to transactions processed using an EMV chip. `misuse` - Misuse. The Fee applies only to either misused or not misused transactions. `bin` - Bin. The Fee applies only to transactions where the payment method matches the given bin number. `fundingCurrencyEqual` - Funding Currency. The Fee applies only to transactions where the funding currencys equals the given currency. `fundingCurrencyNotEqual` - Funding Currency. The Fee applies only to transactions where the funding currencys does not equal the given currency. `fundingCurrencyMismatch` - Funding Currency. The Fee applies only to transactions where the funding currency and purchase currency does not match. `fundingEnabled` - Funding Enabled. The Fee applies only to transactions with the given fundingCurrency value. `settledCurrencyMismatch` - Funding Currency. The Fee applies only to transactions where the funding currency and settled currency does not match. `status` - Txn Status. The Fee applies based on the txn status.
`application`	string	When this Fee Rule will be applied.	`both` - Both. The rule should apply to the fee and to the calculation of collections. `fee` - Fee. The rule should apply only to the fee itself. `collection` - Collection. The fee should be only used when calculating a collection.
`value`	string	This field refers to either the numerical amount for `type` parameter selections that require an amount. This field can also use a set of valid, non-numerical values that specify the Fee Rule value that triggers the type. The following Fee Types are applicable: `swiped` `signed` `type` `origin` `method` `interchange` `cvvResult` `avsResult` `3dsResult` `merchantCountry` `issuerCountry` `international` `platform` `methodType` `emv` `misuse` `fundingCurrencyMismatch` `fundingEnabled` `settledCurrencyMismatch` `status` Note: `mcc` & `bin` value parameters are technically numerically formatted values but each have specific valid values that cannot be covered comprehensively here. See the `mcc` & `bin` sections of the Valid Values column for more information.	The following `type` parameters use a `true` or `false` value to specify whether or not the specific action or event occured: `swiped` - Card was swiped. `signed` - Cardholder signature captured. `related` - Related to another transaction. `entity` - `international`- Transaction is international `emv` - Card was “dipped” (chip inserted). `misuse` - Misuse was detected. `fundingCurrencyMismatch` - The funding currency type does not match the transaction currency. `fundingEnabled`- Funding currency was specified for the transaction. `settledCurrencyMismatch` - The settled currency type does not match the transaction currency. `imported` - The transaction was imported from another platform. `sameDay` - A same-day withdrawal payout of a transaction’s funds to the Merchant occured. See the remaining `value` valid values by `type`: `type` Valid Values: `auth` - Credit Card Only: Auth Transaction. Authorizes and holds the requested total on the credit card. `unauth` - Credit Card Only: Reverse Authorization. Reverses a prior Auth or Sale Transaction and releases the credit hold. `sale` - Credit Card Only: Sale Transaction. Processes a sale and charges the customer. `refund` - Credit Card Only: Refund Transaction. Refunds a prior Capture or Sale Transaction (total may be specified for a partial refund). `capture` - Credit Card Only: Capture Transaction. Finalizes a prior Auth Transaction and charges the customer. `ecsale` - eCheck Only: eCheck Sale Transaction. Sale Transaction for eCheck payment. `ecrefund` - eCheck Only: eCheck Refund Transaction. Refund Transaction for prior eCheck Sale Transaction. `ecredeposit` - eCheck Only: eCheck Redeposit Transaction. Attempt to redeposit a prior failed eCheck Sale Transaction. `ecverify` - eCheck Only: eCheck Account Verification Transaction. Attempt to verify eCheck payment details. `origin` Valid Values: `terminal` - Originated at a credit card terminal. `ecommerce` - Originated through an eCommerce system. `moto` - Originated as a mail order or telephone order transaction. `applePay` - Originated with Apple Pay. `3dsAuth` - Originated as a Successful 3D Secure transaction. `3dsAtt` - Originated as an Attempted 3D Secure transaction. `subscription` - Originated as a recurring transaction on the card. `payFrame` - Originated in a PayFrame. `method` Valid Values: `amex` - American Express `visa` - Visa `mc` - MasterCard `diners` - Diner's Club `discover` - Discover `paypal` - PayPal `debit` - Debit Card `checking` - Checking Account `savings` - Savings Account `giftCard` - Gift Card `ebt` - Electronic Benefits Transfer Card `wic` - Women Infants and Children Card `methodType` Valid Values: `credit` - Credit Card `debit` - Debit Card `debitCredit` - Debit & Credit Card `charge` - Charge Card `prepaid` - Prepaid Card `bankAccount` - ACH Payment `platform` Valid Values: `apple` - Apple processor `elavon` - Elavon processor `fedach` - The U.S. Federal ACH system `firstdata` - First Data processor `payrix` - Payrix mobile `tdbank` - TD Bank ACH funding service `tdbankca` - TD Bank Canadian EFT funding service `vantiv` - The WorldPay (aka Vantiv or Litle) eComm (aka VAP) processor `wellsach` - Wells Fargo ACH funding service. `wellsfargo` - Wells Fargo Merchant Services processor `wfsingle` - Wells Fargo single processor `interchange` Valid Values: `flatRate` - Merchants are charged a fixed percentage fee and a fixed transaction fee for each transaction. `costPlus` - Also known as Interchange Plus, Merchants are charged two separate fees: the interchange fee and the markup. `tiered` - Merchants are charged a varying surcharge based on Risk level. `cvvResult` Valid Values: `match` - The CVV matches the cardholder info. `noMatch` - The CVV does not match the cardholder info. `unavailable` - The CVV verification service is unavailable. `avsResult` Valid Values: `match` - The Address Verification Service (AVS) matched the Cardholder data. `noMatch` - The AVS found no matches for any Cardholder data. `zipNoMatch` - The AVS found no matching zip/postal code. `addressNoMatch` - The AVS found no matches for the Cardholder Address. `nameNoMatch` - The AVS found no matches for the Cardholder name at the associated address. `namePhoneNoMatch` - The AVS found no match for Cardholder name or phone number. `emailNoMatch` - The AVS found no match for Cardholder email address. `phoneNoMatch` - The AVS found no match for Cardholder phone number. `phoneEmailNoMatch` - The AVS found no match for Cardholder phone number or email address. `nameUnavailable` - The AVS name verification service is unavailable. `namePhoneUnavailable` - The AVS name and phone number verification services are unavailable. `nameEmailUnavailable` - The AVS name and email address verification services are unavailable. `phoneUnavailable` - The AVS phone number verification service is unavailable. `phoneEmailUnavailable` - The AVS phone number and email address verification services are unavailable. `emailUnavailable` - The AVS email address verification service is unavailable. `unavailable` - All AVS verification services are unavailable. `3dsResult` Valid Values: `3dsAuthenticationSuccessful` - The 3DS transaction authentication was successful. `3dsAuthenticationNotValid`ated - The 3DS transaction authentication could not be validated. `3dsAuthenticationFailed` - The transaction failed 3DS authentication. `3dsAuthenticationInvalid` - The transaction data provided for 3DS authentication was incomplete or malformed. `3dsAuthenticationSuccessfulWithoutLiabilityShift` - The 3DS transaction authentication was successful but transaction fraud liability will remain with the Merchant in the case of a future chargeback. `merchantCountry` Format Format: 3-digit Alpha-3 country ISO code. Examples: `USA` - The United States `CAN` - Canada `issuerCountry` Format Format: 3-digit Alpha-3 country ISO code. Examples: `USA` - The United States `CAN` - Canada `status` Valid Values: `pending` - Transaction is pending, has not yet been sent to the processor `approved` - Transaction is approved `failed` - Transaction has failed, either declined through the processor or failed processing internally `captured` - Transaction has been settled to the processor (captured) `settled` - Transaction funds have been settled from the issuer to the processor (settled) `returned` - For eCheck transactions: the transaction has been returned by the receiver `bin` - The Bank Issuer Number for the card used in the transaction following the Issuer's formatting. Tip: You can find this by making a request to the `GET /bins` endpoint. `mcc` - The 4-digit Merchant Category code following the ISO 18245 classification.
`grouping`	integer	Determines which rule will be chosen between two or more rule configurations. The “or” logic will decide how to refine the Fee Schedule between two or more rules based on the criteria of the rule met first. The “and” logic will apply all rules to refine the Fee Schedule.	Valid Values: `0` - Use "or" multi-Fee Rule single-choice logic. `1` - Use "and" multi-Fee Rule combination logic.
`inactive`	integer	Whether or not this Fee Rule is inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	integer	Whether or not this Fee Rule has been frozen.	Valid Values: `0` - Not Frozen `1` - Frozen

Additional Resources

For additional Fee-related resources, see the associated articles: