Commission fee

Harbor provides support for setting transaction commissions to ensure revenue generation on every Transfer.

Commission

commission_fee = (total * commission.percentage) + commission.amount

Example Calculation

• commission: percentage = 1.05%, amount = 1.00 USD
• source.amount = 100.00 USD

commission_fee = 100(total) * 1.05%(commsion.percentage) + 1.00(commission.amount) = 2.05

1. Source Amount Model (source.amount is fixed)

The payer sends a fixed source amount.
The destination amount is calculated after deducting commission.

destination.amount = source.amount - commission_fee

Restriction:
A maximum commission rate is enforced because the destination amount cannot be negative.

2. Destination Amount Model (destination.amount is fixed)

The recipient receives a fixed destination amount.
The required source amount increases to cover the commission.

source.amount = destination.amount + commission_fee

No technical limit:
The system can always compute a valid source.amount, so no maximum commission limit is required.

📘

Markup Percentage Limitation

When the transaction uses the source.amount (i.e., the payer sends a fixed amount), the system will enforce a maximum markup limit. This is because excessive markup may result in an invalid or negative destination amount.

For the destination.amount, no technical markup limit is required, as the payer’s required amount will automatically adjust to cover the markup.

Example Code:

curl --location 'https://harbor-sandbox.owlpay.com/applications/v1/transfer' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
    "on_behalf_of": "{{YOUR_CUSTOMER_UUID}}",
    "commission": {
        "percentage": "1.05",
        "amount": "1.00",
    },
    "source": {
        "asset": "USD",
        "amount": "100.00",
    },
    "destination": {
        "asset": "USDC",
        "chain": "ethereum",
        "address": "0xOOOOXXXXXX1234567890"
    },
    "application_transfer_uuid": "{{YOUR_APPLICATION_TRANSFER_UUID}}"
}'

{
    "source": {
        "asset": "USD",
        "amount": "100.00",
    },
    "destination": {
        "asset": "USDC",
        "payment_rail": "ethereum",
        "address": "0x4B20993Bc481177ec7E8f571ceCaE8A9e22C02db",
        "amount": "98.00",
    },
    ...
    "commission": {
        "percentage": "1.05",
        "amount": "1.00",
    },
    "receipt": {
      "initial_amount": "100.00",
      "commission_fee": "2.05",
      "harbor_fee": "0",
      "final_amount": "97.95",
      ...
    },
    ...
}