Fees API
Retrieve your fee schedule and calculate exact fees before transactions. Essential for showing users the final amount.
💡 Best Practice
Always calculate and display fees to users before they confirm a transaction. This prevents surprises and reduces support requests.
Get Fee Schedule
/fees
Retrieve your configured fee rates for pay-user and collect-from-user transactions.
Example Request
curl https://hoopaywallet.com/api/v1/partner/fees \
-H "X-API-Key: hpk_sandbox_your_key" \
-H "X-Signature: your_hmac_signature"Response 200 OK
{
"success": true,
"data": {
"fees": {
"pay-user": {
"percentage": 0.00,
"flat": 0.00,
"min": null,
"max": null
},
"collection": {
"percentage": 1.50,
"flat": 0.50,
"min": 1.00,
"max": 50.00
}
},
"currency": "USD",
"description": {
"percentage": "Percentage of transaction amount",
"flat": "Fixed fee added to each transaction",
"min": "Minimum fee that will be charged",
"max": "Maximum fee that will be charged",
"collection_method": "deduct = fee deducted from amount, add = fee charged separately"
}
}
}Calculate Fee
/fees/calculate
Calculate the exact fee for a specific transaction amount. Use this to show users the breakdown before they confirm.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | pay-user or collect-from-user |
amount |
number | Yes | Transaction amount (min: 0.01) |
Example Request
curl -X POST https://hoopaywallet.com/api/v1/partner/fees/calculate \
-H "Content-Type: application/json" \
-H "X-API-Key: hpk_sandbox_your_key" \
-H "X-Signature: your_hmac_signature" \
-d '{
"type": "collection",
"amount": 100.00
}'Response 200 OK
{
"success": true,
"data": {
"type": "collection",
"amount": 100.00,
"fee_amount": 2.00,
"net_amount": 98.00,
"fee_breakdown": {
"percentage_rate": 1.50,
"flat_fee": 0.50
},
"currency": "USD"
}
}Fee Calculation Logic
Fees are calculated using this formula:
fee = (amount × percentage / 100) + flat_fee
Example Calculation
Amount: $100.00
Percentage Rate: 1.5%
Flat Fee: $0.50
Calculation: ($100 × 1.5%) + $0.50 = $1.50 + $0.50 = $2.00
Net Amount: $100.00 - $2.00 = $98.00
Minimum & Maximum Fees
Some transaction types have minimum and maximum fee caps:
Minimum Fee
If the calculated fee is less than the minimum, the minimum fee is charged instead.
Example: Calculated fee = $0.50, Min fee = $1.00 → Actual fee = $1.00
Maximum Fee
If the calculated fee exceeds the maximum, the maximum fee is charged instead.
Example: Calculated fee = $75.00, Max fee = $50.00 → Actual fee = $50.00
Displaying Fees to Users
Here's how to show a fee breakdown in your UI: