Skip to main content
Skip table of contents

How to Use Fee Listeners

How To - This guide provides step-by-step instructions on how to create and utilize a Fee Listener within the Payrix Portal and via the Payrix API.

A Fee Listener is a back-end layer of Fees that triggers per transaction when an applicable fee type is submitted.

How To Set Up a Fee Listener in the Portal

Part 1: Create a Group

Step 1: From your Dashboard, go to Groups (located under the management category)

Step 2: Click the (plus) ADD GROUP button. Name your new group and click the CREATE GROUP button.

Part 2: Add Fees to your Group

Step 3: From the list of Groups, click on your newly created group to reveal its Group profile menu

Step 4: Go to Fees (located on the left submenu column) and click the (plus) ADD FEES button to reveal the ADD FEE lightbox.

Part 3: Configure your Fee Conditions

Step 5: Within, select AUTH from WHEN TO TRIGGER THE FEE? (The event or time span that triggers assessment of fees)

For time-based triggers, another field will appear - EVERY HOW MANY DAILY (the number of days between each fee assessment)

Step 6: Select HOW MUCH IS THE FEE? to select the type of fee charge (Fixed Rate, Surcharge, or Percentage) and input the numerical amount of the fee to be assessed.

Fee Type Formats

Actual or Surcharge format - $XX.XX

Percentage format - 000.00%

Step 7: Set the FEE START DATE and FEE NAME

Step 8: After the initial Fee setup is complete, click on ADVANCED OPTIONS.

Step 9: Check the Transaction Fee box.

Step 10: Set the Transaction Fee parameters:

  • Currency (Currently, only USD is allowed for US customers)

  • Collection (The frequency and type of collection method for transaction fees)

Step 11: Set Conditional Rule(s) to specify exact criteria for when and why the fee is to be triggered and assessed.

Step 12: When complete, click the ADD button to be brought back to the Fees submenu.

Part 4: Add Merchants to your Fee Group

Step 13: At the bottom of the Group profile page, click the (plus) ADD MEMBERS button to add desired merchants as members of your newly created fee group.

To add a Fee Listener to an Existing fee:

  1. Open the Fee


  3. Check the “Transaction Fee” box.

How To Set Up a Fee Listener via the API

To set up a Fee Listener via the API:

  1. Setup a POST call using the /fees Endpoint.

  2. Set the um value to your desired Fee Charge Type (see below)

  3. Set the amount value to desired fee percentage or amount (based on your Fee Charge Type)

  4. Set the currency value to USD

  5. Set the txnFee value to 1 (representing true)


  • Endpoint = /fees

  • txnFee value =

    • 1 (true)

    • 0 (false)

  • um value =

    • 1 (fixed amount)

    • 2 (percentage)

    • 3 (surcharge)

  • amount value = 10000 (100% or 100.00)

Note: txnFee value of null or 0 only records the transaction for reporting. Fees will not be charged.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.