Home
Guides
Developer Dashboard

Fee Collection

You can charge a custom fee from your end-users when they perform any type of transactions

Suggest Edits

Introduction

We allow developers (you) to charge a fee from the end-user for all types of transactions, including crypto-to-crypto, crypto-to-fiat, and fiat-to-crypto. The fee charging mechanism involves a developer user object and a HIFI-deployed smart contract responsible for stablecoin movement.

Create a Developer User

Before charging transaction fees, you must create a developer user object responsible for managing the fee wallet. This developer user object is similar to the individual HIFI user object created using the create user endpoint. It also has the ability to transfer/withdraw stablecoins to other crypto wallets or use HIFI's rails to withdraw funds into a fiat bank account and is subject to compliance screening.

Click here to create your developer user

Once the developer user object is created and successfully passes the KYC application, you will see the following two sections under your developer dashboard. After that, you can collect transaction fees from your end user.

If you encounter any issues creating the developer user, please contact HIFI for assistance.

Fee Collection

In our transfer endpoints, you can pass feeType and feeValue as additional parameters to specify the fee for a transaction based on your configuration. Note that the fee is subtracted from the transaction amount directly.

There are two feeType options to manage the fee you wish to charge:

  1. PERCENT
  2. FIX

PERCENT

When using PERCENT as the feeType, the fee is calculated as a percentage of the transaction amount, based on the feeValue you set. The following example illustrates how this works:

Example:

For a transaction with a sending amount of $100, where feeType is set to PERCENT and feeValue is set to 0.01, you intend to charge a 1% fee on the transaction amount. The fee would be $1 ($100 * 0.01 = $1). After the transaction is completed, the recipient will receive $99, and $1 will be sent to the developer user's fee collection wallet.

Note: The fee amount is automatically rounded to two decimal places. If the calculated fee is less than $0.01, it will be rounded up to $0.01.


FIX

When using FIX as the feeType, the amount of fee will be the exact feeValue you set. The following example illustrates how this works:

Example:
For a transaction with a sending amount of $100, where feeType is set to FIX and feeValue is set to 0.5, you intend to charge a $0.5 fee on the transaction amount. After the transaction is completed, the recipient will receive $99.5, and $0.5 will be sent to the developer user's fee collection wallet.


How the Smart Contract Works

To ensure that fees are only charged when a transaction is successful—meaning no fee is charged if the recipient doesn't receive the funds—we've implemented a payment processor contract to handle money movement. This leverages the all or nothing nature of blockchain technology, ensuring that fees are only applied upon successful transactions.

There are two key aspects of the implementation:

Fee Wallet Registration

Only wallet addresses registered in the smart contract can be designated as the destination for collected fees. The registration process can ONLY be performed by the HIFI admin wallet. If a fee collection wallet is compromised, the HIFI admin has the authority to remove the compromised wallet from the registration list.

Token Approve

By default, we approve our payment processor to manage up to 1 million tokens on each user's wallet using the ERC20 approve function to optimize gas fee usage. Even with this approval, the transaction must still be initiated from the user's wallet—HIFI and the smart contract do not have the authority to initiate the transaction. This approach ensures the most optimal and secure process.

Integration in Your Transfer

We will use a Transfer Stablecoin to Fiat transaction as an example to demonstrate the fee collection feature. In addition to the usual parameters required, you should specify thefeeType and feeValue in the transfer request body.

curl --request POST \
     --url https://production.hifibridge.com/transfer/crypto-to-fiat \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_123456789' \
     --header 'content-type: application/json' \
     --data '
{
  "sourceCurrency": "usdc",
  "destinationCurrency": "usd",
  "chain": "POLYGON_MAINNET",
  "requestId": "233fb9a1-cf0d-425a-9d71-2f4b84040160",
  "sourceUserId": "75d7c01f-5f93-2344-8b93-a62fd8020358",
  "destinationAccountId": "daa6ad75-1234-486f-a937-1bbf4d19553c",
  "amount": 100,
  "feeType": "PERCENT",
  "feeValue": 0.01
}
'

In the above example, you wish to charge a 1 % fee on the transaction amount. Below is the example transaction result.

{
    "transferType": "CRYPTO_TO_FIAT",
    "transferDetails": {
        "id": "7b7e012e-5c19-4398-b5c0-158ac6dd4fe6",
        "requestId": "233fb9a1-cf0d-425a-9d71-2f4b84040160",
        "sourceUserId": "75d7c01f-5f93-2344-8b93-a62fd8020358 ",
        "destinationUserId": "75d7c01f-5f93-4490-8b93-a62fd8020358",
        "chain": "POLYGON_MAINNET",
        "sourceCurrency": "usdc",
        "amount": 100,
        "destinationCurrency": "usd",
        "liquidationAddress": null,
        "destinationAccountId": "daa6ad75-1234-486f-a937-1bbf4d19553c",
        "transactionHash": null,
        "createdAt": "2024-08-11T03:35:30.921875+00:00",
        "updatedAt": "2024-08-11T03:35:30.921875+00:00",
        "status": "CREATED",
        "contractAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
        "sourceUser": {
            "business_name": null,
            "legal_last_name": "YANG",
            "compliance_email": "[email protected]",
            "legal_first_name": "William"
        },
        "destinationUser": {
            "business_name": null,
            "legal_last_name": "Strumen",
            "compliance_email": "[email protected]",
            "legal_first_name": "Mark"
        },
        "destinationAccount": {
            "id": "daa6ad75-a4c2-486f-a937-1bbf4d19553c",
            "account_owner_name": "Mark Strumen",
            "bank_name": "Bank of America",
            "account_number": "482343817874",
            "routing_number": "021223322",
            "account_type": "us",
            "business_identifier_code": null,
            "bank_country": null,
            "iban": null,
            "beneficiary_first_name": null,
            "beneficiary_last_name": null
        },
        "failedReason": null,
        "fee": {
            "feeId": "20719aea-411f-4e0a-b377-61163c09435a",
            "feeType": "PERCENT",
            "feeAmount": 1,
            "feePercent": 0.01,
            "status": "CREATED",
            "transactionHash": null,
            "failedReason": null
        },
        "conversionRate": {
            "vaildFrom": "2024-08-11T03:35:30.809Z",
            "toCurrency": "usd",
            "vaildUntil": "2024-08-11T03:36:00.809Z",
            "fromCurrency": "usdc",
            "conversionRate": 1
        }
    }
}

Updated about 1 month ago