Eligibility and Requirements

To use Custom Fees, the following conditions must be met:

Partner Brand Configuration:

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

Transaction Type Restrictions:

• The transaction must not be a surcharged transaction.
• The transaction must not involve Google Pay, Apple Pay, or be a card-present transaction (e.g., transactions processed through physical terminals).
• The transaction must not be a Trust account transaction.

Custom Fee Amount:

• The Custom Fee specified must be greater than the standard fee for the merchant account.
• The Custom Fee must not exceed the transaction total.

Implementation Guide

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

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

Step 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."
  }
}

Step 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

Applying a Custom Fee Successfully

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
  }
}

Reponse:

{
  "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."
  }
}

Custom Fee Not Applied Due to Transaction Type

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

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.

If the Custom Fee is not applied, the response will include the meta.customFeeMessage field explaining why.

Possiblemeta.customFeeMessage Values:

Best Practices

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.

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

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]