Skip to main content

Create a Custom Fee

Suggest Edits

Overview​

Create a custom (one-time) fee to be charged to a merchant. Custom fees allow you to charge merchants for special services, monthly fees, or any other charges outside of normal transaction processing fees.

Resource Access​

Production (api.ahrvo.network)

POST https://api.ahrvo.network/payments/na/fees

Staging (gateway.ahrvo.network)

POST http://gateway.ahrvo.network/payments/na/fees

Arguments​

AttributeMandatory / OptionalDescription
Finix-VersionMandatorySpecify the API version (e.g., 2022-02-01)
amountMandatoryThe fee amount in cents (e.g., 100 for $1.00)
currencyMandatoryThe currency of the fee (e.g., USD)
fee_subtypeMandatoryFor custom fees, this must be CUSTOM
fee_typeMandatoryFor custom fees, this must be CUSTOM
merchantMandatoryID of the merchant who will be charged the fee
display_nameOptionalUser-friendly name for the fee
tagsOptionalKey-value metadata to attach to the fee

Example Request​

curl -X POST https://gateway.ahrvo.network/payments/na/fees \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64_encoded_credentials>" \
  -H "Finix-Version: 2022-02-01" \
  -d '{
    "amount": 2500,
    "currency": "USD",
    "display_name": "December_Monthly_Service_Fee",
    "fee_subtype": "CUSTOM",
    "fee_type": "CUSTOM",
    "merchant": "MRxxxxxxxxxxxxxxxxxx",
    "tags": {
      "billing_period": "2025-12",
      "category": "monthly_service_fee"
    }
  }'

Example Response​

{
  "id": "FExxxxxxxxxxxxxxxxxx",
  "created_at": "2025-12-10T16:00:00Z",
  "updated_at": "2025-12-10T16:00:00Z",
  "amount": 2500,
  "currency": "USD",
  "category": "PROCESSOR",
  "display_name": "December_Monthly_Service_Fee",
  "fee_subtype": "CUSTOM",
  "fee_type": "CUSTOM",
  "label": null,
  "linked_to": null,
  "linked_type": null,
  "merchant": "MRxxxxxxxxxxxxxxxxxx",
  "tags": {
    "billing_period": "2025-12",
    "category": "monthly_service_fee"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/fees/FExxxxxxxxxxxxxxxxxx"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MRxxxxxxxxxxxxxxxxxx"
    }
  }
}

Important Notes​

  • Custom Fee Requirements: Both fee_type and fee_subtype must be set to CUSTOM for manual fees
  • Amount in Cents: The amount is specified in cents (e.g., 2500 = $25.00)
  • No Linked Resource: Custom fees are not linked to transfers or authorizations (linked_to and linked_type will be null)
  • Immediate Charge: The fee is charged immediately to the merchant's account
  • Settlement: Custom fees are included in the next settlement cycle

Common Use Cases​

  • Monthly service fees
  • Setup or onboarding fees
  • Special service charges
  • Account maintenance fees
  • Compliance or regulatory fees
  • One-time charges for specific services

API Documentation​