It is important to understand and correctly configure Fees during an implementation to Payrix. Fees are an integral component of the Payrix platform, which instruct the platform as to how much an entity should be charged in the event of a specific trigger (scheduled or event-based), and to whom those entities pay the amount of that fee.

Fee Overview

Fees can be created and configured at multiple levels, each with a different scope and each with it’s own applicable use case. The following is the most pertinent subset of properties on a Payrix API Fee object:

fees.entity: This Entity ID value for the entity which is to receive the fee amount.

fees.forEntity: The Entity ID value for the entity to which this fee is charged (whomever is paying the fee).

fees.org: The Payrix Org ID (aka Group ID) value for the group to which all member entities have this fee applied.

A fee is associated to either an entity (via the forEntity property) or a group (org) via the org property.

fees.schedule: The trigger schedule or event on which a fee is assessed.

fees.scheduleFactor: A multiplication factor of the schedule value set in fees.schedule, when the configured fees.schedule value is set to a duration-based trigger, such as daily, weekly, monthly, or annually.

Example: To setup a fee that occurs on every week the fees.schedule value would be 2 (Weekly) and the fees.scheduleFactor would be 1 to occur every week.

fees.um: The unit of measurement applying to the amount of this fee: percentage points, fixed amount in cents, or a percentage of the related event amount as a surcharge. In the case of a surcharge fee, the total of a transaction should include the fee amount, the fee amount is not added to the total.

A surcharge fee and percentage fee (1 and 3 respectively) only make sense where the fees.schedule is set to trigger when a monetary event happens, such as an authorization, capture, or refund.

fees.amount: The total amount of this fee to be charged. The units used in this field are determined by the value of the fees.um field.

Example: To setup a 3% Authorization fee the fees.um value would be 1 (Percentage Fee) and the fees.amount would be 300.

Implementation of Fees

There are 3 ways in which fees can be configured in the Payrix Platform:

  1. Directly on Merchants (Entities)

  2. More Broadly on Groups (Orgs)

  3. Per Transaction

Configuring Fees Directly on Merchants (Entities)

The simplest and most direct method for configuring Fees is to do so directly on a merchant’s account (Entity). When such a Fee is created via the API, it is applied directly to an Entity by setting the Fee object’s fees.entity property value to the merchant’s entity ID.

When such a Fee is created within the Payrix Portal, it is done on the Merchant’s Account Overview page, under Account Overview, within the “FEES” sub-tab. Clicking the plus “+” action button next to the “FEES” heading will present you with a modal dialog in which you create a new Fee on the current Merchant:

When to trigger the fee? *: This equates to the API-level fees.schedule value, above.

How much is the fee? *: This equates to the fees.um value, above, the units of measurement for the amount value.

Amount *: This equates to the fees.amount value, above,

Configuring Fees On Groups (Orgs)

Much like configuring Fees directly on Merchants (Entities), doing so on Groups (Orgs) can be done via both the Payrix API and the Portal. The difference in choosing to configure Fees on a group is that the configured Fees will then apply to all Entities who are members of the group.

When using the API to create Fees, instead of setting the Fee object’s entity property value, set the org property value to the ID of the Group (Org) on which you want to create the Fee. Subsequently every member entity of the group will be charged the fee when they trigger the configured schedule.

Configuring a Fee on a Group in the Portal is very similar to doing so directly on a Merchant. However, instead of adding the Fee on a Merchant’s profile page, you do so on Group profile page. Under “GROUP”, within the “FEES” sub-tab. Clicking the plus “+ Add Fee” action button next to the “FEES” heading will present you with a modal dialog in which you create a new Fee on the current Group.

Submitting Fees Per Transaction (Fee Listener)

In the instance where a partner wants to calculate the fees on their back-end and submit, this can be done by setting up a “Fee Listener”. This is a fee that will use value within the txns.fee field of the transaction as the fee amount.

A Fee Listener can be setup on an existing Fee within the Portal by setting “Transaction Fee” to Yes.

The setting in the Portal can only be applied after the fee has been created, not during the time of creation.

To create the fee via the API submit a request to the /fees endpoint with the fees.txnFee field value of 1 True and the fees.um field value of 2 Percentage and the fees.amount field value of 10000. This is an indicator to charge 100% of the amount provided within each transaction request’s txns.fee field as the fee.

Without the fee.txnFee field, any amount submitted within the txns.fee field is for reporting purposes only and will not be calculated or charged as a fee.

Here is an example of setting up a “Fee Listener” on a Org:

{
  "id": "t1_fee_ID",
  "entity": "t1_ent_ID",
  "forentity": null,
  "org": "t1_org_ID",
  "type": 1,
  "name": "Auth Fee Listener",
  "schedule": 6,
  "scheduleFactor": 1,
  "um": 1,
  "amount": 10000,
  "txnFee": 1,
}
JS

Using the above example fee, in order to charge a $3 fee on a $100 transaction the transaction txns.total would be $100 (value of 10000) and the transaction txns.fee would be $3 (value of 300). The resulting transaction would appear like this in the Portal:

Fee Modifiers

Changing the Fee Paying Entity

In some instances it becomes necessary to change the entity to whom the fee amount is charged. This can be done with a feeModifiers. A fee modifier can be created associated with a specific fee by setting the fee modifier’s feeModifiers.fee property to the ID of the relevant fee. In order to change the entity who pays the fee, set the fee modifier’s feeModifiers.fromentity property to the ID of the entity to whom the fee will be charged.

This can also be configured while creating a fee in the Portal, under the “Advanced Options” section of the new fee:

The Charging Entity will always be associated the entities.login that created the fee.