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

GET /fees

Retrieve your configured fee rates for pay-user and collect-from-user transactions.

Example Request

cURL

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

JSON

{
  "success": true,
  "data": {
    "fees": {
      "pay-user": {
        "percentage": 0.00,
        "min": null,
        "max": null
      },
      "collection": {
        "percentage": 1.50,
        "min": 1.00,
        "max": 50.00
      }
    },
    "currency": "USD",
    "description": {
      "percentage": "Percentage of transaction amount",
      "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

POST /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

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

JSON

{
  "success": true,
  "data": {
    "type": "collection",
    "amount": 100.00,
    "fee_amount": 1.50,
    "net_amount": 98.50,
    "fee_breakdown": {
      "percentage_rate": 1.50
    },
    "currency": "USD"
  }
}

Fee Calculation Logic

Fees are calculated using this formula:

fee = amount × percentage / 100

Example Calculation

Amount: $100.00

Percentage Rate: 1.5%

Calculation: $100 × 1.5% = $1.50

Net Amount: $100.00 - $1.50 = $98.50

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.30, 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:

Collection Summary

Collection Amount $100.00

Fee (1.5%) -$1.50

You'll receive $98.50

Previous Refunds

Next Merchant Wallets