Managing Fee Profiles

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

Setting a fee profile is a two-step process:

  1. Create a fee_profile
  2. 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: Creating a Fee Profile

You can create a fee profile with the following API Request:

Note: This API has a v2 suffix in the API route.

Copy
Copied
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
  }'

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

Note: 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 Type Description Field Minimum Value Field Maximum Value
ach_basis_points integer, optional 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 integer, optional Maximum ach_basis_points fee (in cents) incurred for each individual Transfer. 0 No restrictions
ach_fixed_fee integer, optional Fee in cents incurred for each individual Transfer 0 1000 ($10)
basis_points integer, optional 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 integer, optional Fee in cents incurred for each individual card-based Transfer 0 40 ($0.40)
ach_credit_return_fixed_fee integer, optional 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 integer, optional A fixed amount (in cents) that will be charged to the seller for receiving an ACH Debit Return. 0 500 ($5)
dispute_fixed_fee integer, optional Applied when a dispute is created or moved to state PENDING 0 2000 ($20)
dispute_inquiry_fixed_fee integer, optional Applied when a dispute is created in state INQUIRY 0 2000 ($20)

Example Response

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.

See below for an example of how a response might look like.

Copy
Copied
{
    "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"
        }
    }
}

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.

Example Response:

Copy
Copied
{
  "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.

Copy
Copied
 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" 
  }'

Onlyfee_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.

Example Response:

Copy
Copied
{
    "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"
        }
    }
}