Fee Configuration for Onboarding Applications
Provide feeInformation when creating onboarding applications that will be sent to a signer.
Fees are part of merchant setup. They are submitted through the onboarding APIs, shown in the signing experience, and should be treated as fixed for the application rather than something the signer edits during the hosted flow.
If fee data is incomplete or missing, the application may not board as intended, and wallet tenders may not be made available for the merchant.
Where feeInformation goes
Placement depends on the onboarding flow.
Full application
For the full application flow, include feeInformation inside merchantData.
Short application
For the short application flow, include feeInformation at the top level of the request body.
How fee configuration works
All merchant fees for onboarding come through the application APIs.
That includes:
settlement-related fixed fees
crypto fees
digital wallet fees
These values should be included when the application is created. They are not intended to be negotiated, corrected, or completed later by the signer inside the hosted onboarding flow.
Required fee groups
A typical feeInformation object includes three groups of fees:
settlement fixed fees
crypto fees
digital wallet fees
Settlement fixed fees
Settlement fixed fees apply at the merchant level.
Typical fields include:
achSettlementFixedFeesettlementReturnFixedFeemonthlyMaintenanceFee
These should be provided as part of the onboarding request so the merchant is boarded with the agreed commercial setup.
Crypto fees
Crypto fees are configured using bitcoinFee and stablecoinFee. Each takes a transactionRate and perItemFee. Both fields are optional — include only the ones applicable to the merchant's agreement.
Do not use cryptoFees when submitting an application. That field appears in read responses only and will not be accepted on submission.
Digital wallet fees
Digital wallets are configured differently from crypto.
Digital wallet fees are defined as wallet-specific entries under digitalWalletsFees.
Each entry is tied to:
a wallet tender type
a payment location type
This allows wallet pricing to vary by tender and by channel, such as:
inStoreonline
A merchant may have fee entries for one or many supported digital wallet tenders. Common examples include:
alipaypaypalvenmoweChatPayklarna
If a merchant is expected to support a wallet in more than one channel, provide a separate fee entry for each supported channel.
If a digital wallet fee is not present on the application, that digital wallet will not be available for the merchant.
How wallet availability works
Digital wallet availability depends on the fee entries included on the application.
If a digital wallet fee is not present on the application, that digital wallet will not be available for the merchant.
This is an important setup rule. If a merchant is expected to board with a specific wallet tender, include that wallet's agreed fee entry at application creation time.
Best practice
It is best practice to provide all agreed fees while collecting and submitting the merchant application.
That includes:
the settlement fees
the agreed crypto fee structure
all intended digital wallet fee entries
This is the safest pattern because the merchant can always have tenders disabled later at the merchant, location, or terminal level if needed.
It is generally better to board with the agreed fee-backed tenders configured up front than to omit them during onboarding and try to correct tender availability later.
Recommended implementation approach
When building your onboarding integration:
determine the merchant's agreed commercial setup before creating the application
build
feeInformationfrom that agreementinclude all intended settlement, crypto, and wallet fees
submit the application only after fee configuration is complete
treat missing wallet fee entries as a configuration issue, not as something the signer will fix later
Common mistakes
Sending only settlement fees
If the merchant is expected to board for crypto or digital wallets, settlement fees alone are not enough.
Using cryptoFees on submission
cryptoFees is a read-only response field. When submitting an application, use bitcoinFee and stablecoinFee instead. Sending cryptoFees on submission will result in crypto fees not being applied, which causes boarding to fail.
Omitting wallet fee entries
If a wallet fee entry is missing from the application, that wallet should not be expected to board for the merchant.
Waiting to add agreed fees later
This increases the chance of incomplete merchant setup. It is better to send the agreed fees up front and disable tenders later if needed.
Example feeInformation structure
Related pages
Last updated