Managing Fee Profiles

Learn how to manage Fee Profiles using Finix's API.

Setting a fee profile is a two-step process:

Create a fee_profile
Update your merchant to use this new fee_profile for net new transactions

Certification Recommended

If you are looking to integrate these API calls, we recommend contacting our support team to certify these APIs.

Step 1: Create a Fee Profile

You can create a fee profile with the following API Request. Note that this API includes v2 in the route.

Fee Profile Request

curl "https://finix.sandbox-payments-api.com/v2/fee_profiles" \
    -H "Content-Type: application/vnd.api+json" \
    -u USjVJEMpMosSGRiuSQTzu1CN:8d27813a-1ec7-4a85-9aa2-0b83c893c81a \
    -X POST \
    -d '{
        "ach_basis_points": 20,
        "ach_basis_points_fee_limit": 500,
        "ach_fixed_fee": 30,
        "basis_points": 290,
        "ach_credit_return_fixed_fee": 0,
        "ach_debit_return_fixed_fee": 0,
        "fixed_fee": 30,
        "dispute_fixed_fee": 1500,
        "dispute_inquiry_fixed_fee": 1500
    }'

Fee Profile Response

{
    "id": "FPuwU91NMnzyTX8FQNWCZ8sG",
    "created_at": "2023-02-27T22:40:07.45Z",
    "updated_at": "2023-02-27T22:40:07.45Z",
    "ach_basis_points": 20,
    "ach_credit_return_fixed_fee": 0e-12,
    "ach_debit_return_fixed_fee": 0e-12,
    "ach_fixed_fee": 30,
    "american_express_assessment_basis_points": null,
    "american_express_basis_points": null,
    "american_express_charge_interchange": null,
    "american_express_externally_funded_basis_points": null,
    "american_express_externally_funded_fixed_fee": null,
    "american_express_fixed_fee": null,
    "ancillary_fixed_fee_primary": null,
    "ancillary_fixed_fee_secondary": null,
    "application": "AP2B4KfjaniJfPvs5hvKpGEe",
    "basis_points": 30,
    "charge_interchange": false,
    "diners_club_basis_points": null,
    "diners_club_charge_interchange": null,
    "diners_club_fixed_fee": null,
    "discover_assessments_basis_points": null,
    "discover_basis_points": null,
    "discover_charge_interchange": null,
    "discover_data_usage_fixed_fee": null,
    "discover_externally_funded_basis_points": null,
    "discover_externally_funded_fixed_fee": null,
    "discover_fixed_fee": null,
    "discover_network_authorization_fixed_fee": null,
    "dispute_fixed_fee": 1500,
    "dispute_inquiry_fixed_fee": 1500,
    "externally_funded_basis_points": null,
    "externally_funded_fixed_fee": null,
    "fixed_fee": 100,
    "jcb_basis_points": null,
    "jcb_charge_interchange": null,
    "jcb_fixed_fee": null,
    "mastercard_acquirer_fees_basis_points": null,
    "mastercard_assessments_over1k_basis_points": null,
    "mastercard_assessments_under1k_basis_points": null,
    "mastercard_basis_points": null,
    "mastercard_charge_interchange": null,
    "mastercard_fixed_fee": null,
    "qualified_tiers": null,
    "rounding_mode": "TRANSACTION",
    "tags": {},
    "visa_acquirer_processing_fixed_fee": null,
    "visa_assessments_basis_points": null,
    "visa_base_II_credit_voucher_fixed_fee": null,
    "visa_base_II_system_file_transmission_fixed_fee": null,
    "visa_basis_points": null,
    "visa_charge_interchange": null,
    "visa_credit_voucher_fixed_fee": null,
    "visa_fixed_fee": null,
    "visa_kilobyte_access_fixed_fee": null,
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/v2/fee_profiles/FPuwU91NMnzyTX8FQNWCZ8SG"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/AP2B4KfjaniJfPvs5hvKpGEe"
        }
    }
}

The response will return every field and how it’s currently set. You will want to store the id so you can use it in the future.

You can apply this fee_profile to as many merchants as you’d like. However, changes to the fee_profile will update across all merchants. You may choose to create a new fee_profile for every merchant or re-use one you've created in the past.

Recommended Fees

The following are our recommended fees to configure and the minimums and maximums for each (see here for full list.

Increasing Fees

These fields have maximums our compliance team sets. If you would like to charge your sellers a higher fee than what is described above, please contact our support team to discuss your use case.

Field	Description	Field Minimum Value	Field Maximum Value
`ach_basis_points`	Percentage-based fee incurred against the full amount of an ACH (eCheck Debit). Calculated as one hundredth of one percent (1 basis point = .0001 or .01%).	0	2000 (20%)
`ach_basis_points_fee_limit`	Maximum `ach_basis_points` fee (in cents) incurred for each individual `Transfer`.	0	No restrictions
`ach_fixed_fee`	Fee in cents incurred for each individual `Transfer`.	0	1000 ($10)
`basis_points`	Percentage-based fee incurred against the full amount of each card-based `Transfer`. Calculated as one hundredth of one percent (1 basis point = .0001 or .01%).	25 (.25%)	500 (5%)
`fixed_fee`	Fee in cents incurred for each individual card-based `Transfer`.	0	40 ($0.40)
`ach_credit_return_fixed_fee`	A fixed amount (in cents) that will be charged to the seller for receiving an ACH Credit Return.	0	500 ($5)
`ach_debit_return_fixed_fee`	A fixed amount (in cents) that will be charged to the seller for receiving an ACH Debit Return.	0	500 ($5)
`dispute_fixed_fee`	Applied when a dispute is created or moved to state PENDING.	0	2000 ($20)
`dispute_inquiry_fixed_fee`	Applied when a dispute is created in state INQUIRY.	0	2000 ($20)

Step 2: Updating your Merchant to use a new Fee Profile

To update your seller's fee profile, you need to know the merchant_profile of the merchant.

You can find the merchant_profile in the response body of a merchant. You can get the merchant profile by doing a GET on a merchant. It will be returned in the field called merchant_profile.

Merchant Resource

{
    "id": "MUmUL7aBsHkxVLQawJxEXw6N",
    "created_at": "2022-08-17T20:33:34.04Z",
    "updated_at": "2024-01-22T03:18:01.26Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "convenience_charges_enabled": false,
    "country": null,
    "creating_transfer_from_report_enabled": true,
    "currencies": null,
    "default_partial_authorization_enabled": false,
    "disbursements_ach_pull_enabled": false,
    "disbursements_ach_push_enabled": false,
    "disbursements_card_pull_enabled": false,
    "disbursements_card_push_enabled": false,
    "fee_ready_to_settle_upon": "RECONCILIATION",
    "gateway": null,
    "gross_settlement_enabled": false,
    "identity": "IDrH4G2VTfNjn1VFkvhcyMYj",
    "level_two_level_three_data_enabled": true,
    "mcc": null,
    "merchant_name": "John Smith",
    "merchant_profile": "MPjBZguwk8oJ9H5ouJo3jaG4",
    "mid": "FNXoj46ep1DSantwywsnVtP8J",
    "onboarding_state": "APPROVED",
    "processing_enabled": true,
    "processor": "DUMMY_V1",
    "processor_details": {
        "mid": "FNXoj46ep1DSantwywsnVtP8J",
        "api_key": "secretValue"
    },
    "ready_to_settle_upon": "RECONCILIATION",
    "rent_surcharges_enabled": false,
    "settlement_enabled": true,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {
        "key_2": "value_2"
    },
    "verification": "VIvEoRW1UUces66vGcKFzdrR",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUmUL7aBsHkxVLQawJxEXw6N"
        },
        "identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDrH4G2VTfNjn1VFkvhcyMYj"
        },
        "verifications": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUmUL7aBsHkxVLQawJxEXw6N/verifications"
        },
        "merchant_profile": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPjBZguwk8oJ9H5ouJo3jaG4"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "verification": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VIvEoRW1UUces66vGcKFzdrR"
        }
    }
}

Once you have the merchant_profile and the fee_profile from the previous request, you can run a PUT request on the merchant_profile. After you update the merchant_profile, your merchant will be updated with the fee_profiles you specified. All net new transactions will have this fee_profile. Any transactions that were created before the change will have the previous fee_profile applied.

Updating Merchant Profile

curl "https://finix.sandbox-payments-api.com/merchant_profiles/MPsJL7T9M6GT8G6TWJqsS2yb" \
    -H "Content-Type: application/vnd.api+json" \
    -u USjVJEMpMosSGRiuSQTzu1CN:8d27813a-1ec7-4a85-9aa2-0b83c893c81a \
    -X PUT \
    -d '{
        "fee_profile": "FPuwU91NMnzyTX8FQNWCZ8SG",
        "card_present_fee_profile" : "FPuwU91NMnzyTX8FQNWCZ8SG"
    }'

Only fee_profile is required in the request above.

If you do not supply a card_present_fee_profile, then the fee_profile will be applied to both online an in-person payments.
If a card_present_fee_profile field is provided, then the card_present_fee_profile's fee profile will be used solely for in-person transactions.

Updated Merchant Profile

{
    "id": "MPqwa1AXcfEh5fE4sxrk1HPy",
    "created_at": "2022-06-15T20:03:33.92Z",
    "updated_at": "2024-01-31T00:18:52.29Z",
    "application": "APf2jEV1r8CuHkxK6taZKerR",
    "card_present_fee_profile": "FP7ehCuoYhW7x5UuZjiY5P6b",
    "fee_profile": "FP7ehCuoYhW7x5UuZjiY5P6b",
    "payout_profile": null,
    "risk_profile": "RPgGN6su6ksk8NMSQBoK2VC1",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/merchant_profiles/MPqwa1AXcfEh5fE4sxrk1HPy"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APf2jEV1r8CuHkxK6taZKerR"
        },
        "risk_profile": {
            "href": "https://finix.sandbox-payments-api.com/risk_profiles/RPgGN6su6ksk8NMSQBoK2VC1"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FP7ehCuoYhW7x5UuZjiY5P6b"
        }
    }
}

Managing Fee Profiles

Step 1: Create a Fee Profile

Recommended Fees

Step 2: Updating your Merchant to use a new Fee Profile

Was this helpful?