HomeGuidesRecipesAPI ReferenceChangelog
Log In
Guides

Managing Fees and Commissions

Suggest Edits

Unblock API provides flexible options to manage transaction fees, allowing you to configure commission structures that align with your business model. This guide provides a clear overview of how to configure and manage fees using the Unblock API, ensuring transparency and control over your revenue streams.

Understanding Fee Structure

Unblock operates with two primary types of fees:

  • Unblock Fees: These are the base fees charged by Unblock for processing transactions. Unblock fees are always applied and are independent of your merchant fee configurations. They are designed to cover the operational costs of the Unblock platform.
  • Merchant Fees: These are fees that you, as the integrating merchant, can configure and control. Merchant fees can be added on top of Unblock's fees or used to create custom pricing models.

This guide focuses on how to configure Merchant Fees.

Configuring Merchant Fees: Core Concepts

You can configure merchant fees at different levels and with various parameters to suit your needs:

Fee Value: Percentage-Based Commissions

  • Merchant fees are configured as decimal values, representing a percentage of the transaction amount.
    • Example: 0.01 represents a 1% fee.
    • Example: 0.005 represents a 0.5% fee.

Configuration Scope: Granular Control

Merchant fees can be configured with fine-grained control, based on:

  • Transaction Direction: onramp (fiat-to-crypto) or offramp (crypto-to-fiat).
  • Input Currency: The currency being used as input for the transaction (e.g., EUR, USD, USDC, USDT). For offramp, this typically refers to the crypto token. For onramp, this refers to the fiat currency.
  • Output Currency: The currency being output from the transaction. For onramp, this typically refers to the crypto token. For offramp, this refers to the fiat currency.
  • Configuration Level:
    • Merchant-wide: Applies to all transactions for your merchant account by default.
    • User-specific: Custom fees can be applied to individual users (Individuals or Corporates) using their unique UUIDs, overriding merchant-wide settings.

Fee Operation Types: add and subtract

Unblock API supports two fee operation types:

  • add Fee Type:

    • When using fee_op_type: "add", you increase the total fee charged to the user.
    • The added fee amount is collected by you, the merchant, as additional revenue on top of the Unblock fee.
    • This is the most common fee type, allowing you to add your commission to each transaction.

  • subtract Fee Type:

    • This feature might NOT be active by default for all merchants. Please contact Unblock support to enable it.
    • When using fee_op_type: "subtract", you decrease the total fee effectively charged to the user, potentially subsidizing transactions.
    • The amount subtracted from the user's fee represents a debt owed by you, the merchant, to Unblock. This difference will be invoiced and collected periodically.

Minimum Fee: Ensuring Minimum Revenue

  • You can set a minimum_fee value as a fixed amount in the input currency.
  • If a minimum_fee is configured, the applied merchant fee will be the greater value of either:
    • The calculated percentage-based fee.
    • The fixed minimum_fee amount.
  • This ensures a minimum revenue per transaction, regardless of the transaction size.

Maximum Fee: Setting Limits (Subtract Fee Type)

  • Maximum fee limitations are primarily relevant when using subtract fee type and are often pre-configured by Unblock and not changeable by merchants.
  • For subtract fees, you typically cannot set a fee value that reduces the total fee below zero or exceeds the Unblock fee itself. This prevents scenarios where the merchant fee becomes negative or completely nullifies Unblock's base fee.

API Endpoints for Fee Management

The following API endpoints are used to manage merchant fees:

Example 1: Adding a 1% Fee on all EUR On-ramp Transactions

To add a 1% fee to all fiat-to-crypto transactions where the input currency is EUR, you would use the PATCH /merchant/fees endpoint with the following parameters:

{
  "fee": 0.01,
  "input_currency": "EUR",
  "direction": "onramp",
  "fee_op_type": "add"
}

**Example 2: Setting a Minimum Fee of 2 EUR for EUR Off-ramp Transactions

To ensure a minimum merchant fee of 2 EUR for all crypto-to-fiat transactions where the output currency is EUR, you would use the PATCH /merchant/fees endpoint with the minimum_fee parameter. In this case, the percentage-based fee will still apply if it exceeds 2 EUR.

{
"minimum_fee": 2,
"input_currency": "EUR",
"direction": "offramp"
}

Subsidizing Crypto-to-Fiat transactions by subtracting fee (1% example)

Make sure the subtractfee type is enabled for your merchant account. To reduce the fee by 1% for crypto-to-fiat transactions (off-ramp), you would use the PATCH /merchant/fees endpoint with these parameters. Note that you are now using the minimum configurable fee of 1% for a subtract operation.

{
  "fee": 0.01,
  "input_currency": "USDC", // Example using USDC as input crypto
  "direction": "offramp",
  "fee_op_type": "subtract"
}

Summary

Unblock API's fee management system provides granular control over transaction commissions. By understanding the different configuration options and utilizing the provided API endpoints, you can effectively manage your revenue and offer flexible pricing models to your users. Explore the API Reference for detailed parameter descriptions and request examples for each fee management endpoint.

Updated 16 days ago

What’s Next