Custom Fees Overview

Custom Fees allow partners to specify additional fees for transactions processed through their platform. By leveraging Custom Fees, partners can adjust the fee structure for specific transactions, enabling flexible pricing models tailored to their business needs.

Eligibility and Requirements

Before implementing Custom Fees, ensure all requirements are met:

cog

Partner Brand Configuration

Your partner brand must have Custom Fees enabled. Contact your account manager or support to verify and enable this feature.

ban

Transaction Type Restrictions

Must not be a surcharged transaction
Must not involve Google Pay, Apple Pay, or card-present transactions
Must not be a Trust account transaction

calculator

Custom Fee Amount Rules

Must be greater than the standard fee for the merchant account
Must not exceed the transaction total

Implementation Guide

check-circleStep 1: Ensure Eligibility

Before implementing Custom Fees, confirm that all eligibility criteria are met:

Verify that your partner brand has Custom Fees enabled
Check that the transaction type is supported
Ensure that the merchant account is not a Trust account

codeStep 2: Specify Custom Fee in Transaction Request

When processing a transaction, include the meta.customFee parameter in your API request to specify the Custom Fee amount.

{
  "payment_method_id": "pm_987654321",
  "total": 100.00,
  "meta": {
    "customFee": 2.50
  }
}

exchange-altStep 3: Handle API Responses

The API response will include information about whether the Custom Fee was applied or if there were issues.

Success Response (200 OK):

{
  "id": "txn_123456789",
  "type": "charge",
  "status": "authorized",
  "amount": 100.00,
  "currency": "USD",
  "payment_method_id": "pm_987654321",
  "created_at": "2023-01-01T12:00:00Z",
  "meta": {
    "customFeeApplied": true,
    "customFeeMessage": "Custom fee applied successfully."
  }
}

Example of Response When Custom Fee is Not Applied:

{
  "id": "txn_123456789",
  "type": "charge",
  "status": "authorized",
  "amount": 100.00,
  "currency": "USD",
  "payment_method_id": "pm_987654321",
  "created_at": "2023-01-01T12:00:00Z",
  "meta": {
    "customFeeApplied": false,
    "customFeeMessage": "Custom fee not used, source not allowed."
  }
}

exclamation-triangleStep 4: Communicate Fees to Merchants

Certification Requirement:

You must clearly communicate to the merchant any additional fees assessed due to Custom Fees. Transparency is essential for compliance and maintaining trust with your merchants.

Best Practices:

Disclosure: Inform merchants about the Custom Fee amount and how it affects their transaction costs
Documentation: Provide documentation or agreements that outline the fee structures
Support: Be prepared to address merchant questions regarding Custom Fees

Examples and Use Cases

Scenario:

Partner wants to apply a $2.50 Custom Fee to a $100.00 transaction
All eligibility conditions are met

Request:

{
  "payment_method_id": "pm_987654321",
  "total": 100.00,
  "meta": {
    "customFee": 2.50
  }
}

Response:

{
  "id": "txn_123456789",
  "type": "charge",
  "status": "authorized",
  "amount": 100.00,
  "currency": "USD",
  "payment_method_id": "pm_987654321",
  "created_at": "2023-01-01T12:00:00Z",
  "meta": {
    "customFeeApplied": true,
    "customFeeMessage": "Custom fee applied successfully."
  }
}

Scenario:

Partner attempts to apply a $2.50 Custom Fee to an Apple Pay transaction
Transaction type is not supported

Request:

{
  "payment_method_id": "pm_applepay_123456",
  "total": 100.00,
  "meta": {
    "customFee": 2.50
  }
}

Response:

{
  "id": "txn_987654321",
  "type": "charge",
  "status": "authorized",
  "amount": 100.00,
  "currency": "USD",
  "payment_method_id": "pm_applepay_123456",
  "created_at": "2023-01-01T12:05:00Z",
  "meta": {
    "customFeeApplied": false,
    "customFeeMessage": "Custom fee not used, source not allowed."
  }
}

Error Handling

exclamation-circleCommon Error Messages and Their Meanings

When implementing Custom Fees, it's crucial to handle errors gracefully. Ensure your application:

Checks the meta.customFeeApplied flag to confirm if the Custom Fee was applied
Reads the meta.customFeeMessage to understand why a Custom Fee was not applied
Communicates any issues to the user or merchant appropriately

Possible meta.customFeeMessage Values:

Error	Meaning
`Custom fee not used, unsupported brand.`	Custom Fees are not enabled for your partner brand.
`Custom fee not used, defaulting to minimum fee.`	The Custom Fee provided is not sufficient to cover the minimum fee.
`Custom fee not used, trust accounts do not support custom fees.`	Custom Fees are not supported for Trust accounts.
`Custom fee not used, source not allowed.`	Custom Fees are not supported for this transaction type (e.g., Google Pay, Apple Pay).
`Custom fee not used, surcharged transaction.`	Custom Fees cannot be applied to surcharged transactions.
`Custom fee not used, custom fee is higher than transaction total.`	The Custom Fee exceeds the transaction total.

Best Practices

shield-alt

Validation & Monitoring

Validation: Before submitting a transaction, validate that all eligibility criteria for Custom Fees are met.

Monitoring: Keep logs of transactions and Custom Fee applications for auditing purposes.

book-open

Compliance & Updates

Updates: Stay informed about any changes to Custom Fees policies or eligibility criteria by regularly reviewing the Partner API documentation.

Compliance: Ensure all fee disclosures comply with relevant financial regulations and industry standards.

Contact Support

If you have questions or need assistance with Custom Fees:

Email: [email protected]