Skip to main content

Fees

This page describes fees embedded in the payment quote — what the payer sends on top of the merchant amount. It does not replace hosted platform pricing ($0.10 per transaction on hosted OrcaRail after 1,000 free transactions; self-hosted Open source soon software is free).

OrcaRail can apply up to three types of fees to a payment: support fee, commission fee, and bridge fee. All are expressed in the payer’s token and included in the total amount the payer must send. The quote (and payment intent) responses expose these amounts and flags.

Total amount formula​

The amount the payer must send is:

totalAmount = originalAmountInPayerToken + bridgeFeeInPayerToken + supportAmount + commissionAmount
  • originalAmountInPayerToken — The requested payment amount converted to the payer’s token (before any fees).
  • bridgeFeeInPayerToken — Bridge/swap fee when the payer’s token or network differs from the receivable token/network (from Relay). null when no bridge is required.
  • supportAmount — Optional support fee in payer token (see below).
  • commissionAmount — Optional commission in payer token (see below).

The Get Quote and payment intent quote responses return these fields as defined in the API (e.g. QuoteResponseDto).

Support fee​

  • What it is: An optional percentage of the original amount (the amount the merchant receives).
  • Default: From environment variable PAYMENTS_DEFAULT_SUPPORT_PERCENT. The API default is 1 (1%) when not set.
  • Override: You can override the support percent per quote or transaction via the supportPercent parameter (e.g. in Get Quote or when creating/updating a transaction).
  • Minimum floor: When support percent is greater than 0, the computed support amount is floored to the network minimum for that chain (to avoid dust). The quote includes supportMinimumApplied: true when this floor was applied.
  • Destination: OrcaRail support wallet (configurable server-side).

Support fee (quote response)​

FieldDescription
supportPercentEffective support fee percent applied (string).
supportAmountSupport amount in payer token (string).
supportMinimumAppliedtrue when the support amount was floored to the network minimum.

Commission fee​

  • What it is: An optional percentage of the original amount, configured per API key (commissionPercent). Only applied when the payment link or payment intent is created with that API key.
  • Configuration: Set when creating or updating an API key (Dashboard or API Keys API). If not set, commission is 0.
  • $0.01 USD rule: If the commission amount in USD is less than $0.01, the API sets commission to 0 (no commission is charged).
  • Minimum floor: Same as support: when commission percent is greater than 0, the commission amount is floored to the network minimum. The quote includes commissionMinimumApplied: true when this floor was applied.
  • Destination: API key owner’s withdrawal address for the relevant chain (used when processing withdrawals).

Commission fee (quote response)​

FieldDescription
commissionPercentCommission fee percent (from API key) applied to original amount (string).
commissionAmountCommission amount in payer token (string).
commissionMinimumAppliedtrue when the commission amount was floored to the network minimum.

Bridge fee​

  • When it applies: When the payer’s token or network differs from the receivable token or network, a bridge or swap is required. The bridge fee is the cost of that operation.
  • Source: The fee is obtained from Relay and included in the quote.
  • In total: The bridge fee (in payer token) is included in totalAmount so the payer sends enough to cover the bridge and still deliver the requested amount to the merchant.

Bridge fee (quote response)​

FieldDescription
bridgeFeeBridge/swap fee if applicable (in payer token); null when no bridge.
bridgeFeeUsdBridge fee in USD; null when no bridge.
bridgeFeeInPayerTokenBridge fee in payer token; null when no bridge.
requiresBridgetrue when a bridge/swap is required.

See also​