HomeGuidesRecipesAPI ReferenceChangelog
Log In
Guides
Start typing to search…

Managing Fees and Commissions

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:

  • addFee 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.

  • subtractFee 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 using the Fee Management API endpoints.
  • If a minimum_fee is configured, the applied total fee (Unblock fee + Merchant fee if applicable) will be compared against this minimum_fee. The actual fee charged will be the greater of the calculated total fee or the fixed minimum_fee.
  • This ensures a minimum revenue per transaction, regardless of the transaction size.
  • Important Behavior: If the initial transaction amount provided by the user is less than the applicable minimum_fee, the transaction will still be processed. The full minimum_fee will be deducted from the transaction amount. Consequently, the final amount transferred to the recipient (either fiat or crypto) will be zero (0).
    • Example: If the minimum_fee for EUR off-ramp is 2 EUR, and a user initiates a crypto-to-fiat transaction equivalent to 1.50 EUR, the transaction will proceed, 2 EUR will be charged as the fee, and the user will receive 0 EUR in their bank account.
    • Developers should ensure their application logic accounts for this scenario and consider informing the user appropriately, potentially by validating the amount against the minimum fee before initiating the transaction if desired.

Maximum Fee: Setting Limits (Subtract Fee Type)

  • Maximum fee limitations are primarily relevant when usingsubtract 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