Commission

How It Works

Commission is a fee that you add to a transfer to earn revenue. The Customer pays it, and Harbor pays it to you.

You set it: send commission in the quote request, as a percentage, a fixed amount, or both.
Harbor deducts it: the commission is taken from the transfer, so the recipient gets the amount after the commission.
Harbor pays it to you: each month, Harbor pays you the commissions from completed transfers, after subtracting the Harbor fee. See Fees.

For example, you add a 2 USD commission. If the Customer sends 100 USD, the recipient gets 98 USD:

Sender sends     ██████████████████████████████████████████████████  100.00
Recipient gets   █████████████████████████████████████████████████    98.00
Your commission  █                                                     2.00

If the recipient must get 100 USD, the Customer sends 102 USD:

Sender sends     ██████████████████████████████████████████████████  102.00
Recipient gets   ████████████████████████████████████████████████    100.00
Your commission  █                                                     2.00

In both cases, you earn the 2 USD commission.

The Harbor fee is OwlPay's own fee. It is separate from the commission and isn't taken from the transfer. See Fees.

Calculation

How Harbor calculates the commission.

Field	Type	Description
`percentage`	String	The rate, from 0 to 100. For example, `1.05` is 1.05%.
`amount`	String	A fixed fee, `0` or more. It's in USD, or in the source stablecoin.

You can send either one, or both. A negative value is rejected with 422.

commission_fee
  = (source_amount × commission.percentage ÷ 100) + commission.amount

A percentage is divided by 100, so 1.05 means 1.05%. For example, with percentage 1.05 and amount 1.00 on 100.00 USD, the commission_fee is 100 × 1.05% + 1.00 = 2.05 USD.

Fixed Amount

The request fixes one amount, and Harbor calculates the other. The fixed amount determines how the commission is applied:

POST /api/v2/transfers/quotes

With a fixed source.amount, the sender sends 100 USD. The recipient gets the amount after the commission, returned in destination_amount.

The quote request:

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "source": {
        "country": "US",
        "asset": "USD",
        "amount": 100,
        "type": "individual"
    },
    "destination": {
        "chain": "ethereum",
        "asset": "USDC",
        "type": "individual"
    },
    "commission": {
        "percentage": 1.05,
        "amount": 1
    }
}'

The formula:

commission_fee
  = (source_amount × commission.percentage ÷ 100) + commission.amount

destination_amount
  = source_amount − commission_fee

With the values from the request:

commission_fee
  = (100 × 1.05 ÷ 100) + 1
  = 2.05

destination_amount
  = 100 − 2.05
  = 97.95

Harbor returns:

{
    "data": [
        {
            "payment_method": "DOMESTIC_WIRE",
            "source_amount": "100.00",
            "destination_amount": "97.950000",
            "fees": [
                { "type": "COMMISSION_FEE", "amount": "2.050000" },
                ...
            ],
            ...
        }
    ]
}

If the commission is equal to or more than the amount, the quote returns 422.

With a fixed destination.amount, the recipient gets 100 USDC. The sender sends a larger amount that covers the commission, returned in source_amount.

The quote request:

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "source": {
        "country": "US",
        "asset": "USD",
        "type": "individual"
    },
    "destination": {
        "chain": "ethereum",
        "asset": "USDC",
        "amount": 100,
        "type": "individual"
    },
    "commission": {
        "percentage": 1.05,
        "amount": 1
    }
}'

The formula:

source_amount
  = (destination_amount + commission.amount) ÷ (1 − commission.percentage ÷ 100)

commission_fee
  = (source_amount × commission.percentage ÷ 100) + commission.amount

With the values from the request, rounded up to the cent:

source_amount
  = (100 + 1) ÷ (1 − 0.0105)
  = 101 ÷ 0.9895
  = 102.08

commission_fee
  = (102.08 × 1.05 ÷ 100) + 1
  = 2.07

Harbor returns:

{
    "data": [
        {
            "payment_method": "DOMESTIC_WIRE",
            "source_amount": "102.08",
            "destination_amount": "100.000000",
            "fees": [
                { "type": "COMMISSION_FEE", "amount": "2.070000" },
                ...
            ],
            ...
        }
    ]
}

Harbor rounds source_amount up to the cent. There is no maximum commission.

On-Chain Transfers

An on-chain transfer can also have a network fee. The Customer pays it. Harbor calculates it, and it isn't sent in the request. It is deducted from the same amount as the commission. See Fees.

With a fixed source.amount, the sender sends 500 USDC. Harbor adds a 5 USDC network fee, which is not in the request.

The quote request:

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "source": {
        "chain": "ethereum",
        "asset": "USDC",
        "amount": 500,
        "type": "individual"
    },
    "destination": {
        "chain": "solana",
        "asset": "USDC",
        "type": "individual"
    },
    "commission": {
        "percentage": 3,
        "amount": 0
    }
}'

The formula:

commission_fee
  = (source_amount × commission.percentage ÷ 100) + commission.amount

destination_amount
  = source_amount − commission_fee − network_fee

With the values from the request:

commission_fee
  = (500 × 3 ÷ 100) + 0
  = 15

destination_amount
  = 500 − 15 − 5
  = 480

Harbor returns:

{
    "data": [
        {
            "payment_method": "ON_CHAIN",
            "source_amount": "500.000000",
            "destination_amount": "480.000000",
            "exchange_rate": "0.98969072",
            "fees": [
                { "type": "COMMISSION_FEE", "amount": "15.000000" },
                { "type": "BLOCKCHAIN_NETWORK_FEE", "amount": "5.000000" },
                ...
            ],
            ...
        }
    ]
}

With a fixed destination.amount, the recipient gets 500 USDC. Harbor adds a 5 USDC network fee, which is not in the request.

The quote request:

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/quotes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "source": {
        "chain": "ethereum",
        "asset": "USDC",
        "type": "individual"
    },
    "destination": {
        "chain": "solana",
        "asset": "USDC",
        "amount": 500,
        "type": "individual"
    },
    "commission": {
        "percentage": 3,
        "amount": 0
    }
}'

The formula:

source_amount
  = (destination_amount + network_fee + commission.amount) ÷ (1 − commission.percentage ÷ 100)

commission_fee
  = (source_amount × commission.percentage ÷ 100) + commission.amount

With the values from the request, rounded up to the cent:

source_amount
  = (500 + 5 + 0) ÷ (1 − 0.03)
  = 505 ÷ 0.97
  = 520.62

commission_fee
  = (520.62 × 3 ÷ 100) + 0
  = 15.6186

Harbor returns:

{
    "data": [
        {
            "payment_method": "ON_CHAIN",
            "source_amount": "520.620000",
            "destination_amount": "500.000000",
            "exchange_rate": "0.99009626",
            "fees": [
                { "type": "COMMISSION_FEE", "amount": "15.618600" },
                { "type": "BLOCKCHAIN_NETWORK_FEE", "amount": "5.000000" },
                ...
            ],
            ...
        }
    ]
}

Each quote in data also has an exchange_rate. It is the destination amount divided by the sender's amount after the commission:

exchange_rate
  = destination_amount ÷ (source_amount − commission_fee)

For example, in the source amount tab: 480 ÷ (500 − 15) = 0.98969072. This is the exchange_rate in that response.

For the quote fields, see Quotes.

Examples

Each bar is a share of the sender's amount.

The sender's amount is fixed: 100 USD, 2% commission

Sender sends   ████████████████████████████████████   100.00
Recipient gets ███████████████████████████████████     98.00
Commission     █                                        2.00

The recipient's amount is fixed: 100 USD, 2% commission

Sender sends   ████████████████████████████████████   102.05
Recipient gets ███████████████████████████████████    100.00
Commission     █                                        2.04

No commission

Sender sends   ████████████████████████████████████   100.00
Recipient gets ████████████████████████████████████   100.00
Commission                                              0.00

Notes

A few things to know about commission.

Commission works the same for on-ramp, off-ramp and on-chain transfers. You send it in the commission object of the quote.
Harbor pays the commissions earned each month, after the Harbor fee. See Fees.
Your commission is a share of what the sender sends (source_amount), not of what the recipient gets. So it is not destination_amount × commission.percentage when the destination amount is fixed.
Deposit Accounts also take a commission. See Deposit Accounts.
If a transfer is rejected, expired, cancelled or refunded, you don't earn the commission.