Monetizing HIFIs Endpoints
You can charge a custom fee from your end-users when they perform any type of transactions
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. Please note that the fee is applied in addition to the transaction amount.
There are two feeType
options to manage the fee you wish to charge:
- PERCENT
- 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 exactly $100, and $1 will be sent to the developer user's fee collection wallet. The total amount charged from the user's wallet will be $101.
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 exactly $100, and $0.5 will be sent to the developer user's fee collection wallet. The total amount charged from the user's wallet will be $100.5.
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,
"amountIncludeDeveloperFee": 101,
"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