Application fees
Application fees are non-refundable fees that platforms can charge their connected accounts for Airwallex services offered by the platform such as FX Conversions and Payouts. These fees are separate from fees charged by Airwallex for these services.
This guide describes how platforms can charge application fees when using Airwallex's Conversions and Payouts capabilities.
Conversions
Provide the following fields in the application_fee_options object when you Create a conversion API using Quotes or Rates products:
source_type: Set this toCONVERSION.type: Fee calculation type must be set toPERCENTAGEfor conversions.percentage: The markup on the FX rate expressed as a number between 0 to 20. For example, specifying 0.1 indicates 0.1%. This markup changes the client rate by the specified percentage.currency: Optional. Defaults to the contra currency of the quote. If specified, the currency for the conversion must be from the currency pair.
The response will contain a detailed breakdown of fees paid for the service in the application_fees object. You can retrieve the application fees anytime using Retrieve a conversion API endpoint.
The diagram below shows how application fees are applied to FX rates.
You can also charge application fees for conversion quotes by providing the application_fees_options object in Create a quote API.
Payouts
This feature is currently available in Beta and only applies to individual payouts. Batch payouts, digital Wallet and Airwallex Wallet transfers are currently not supported.
Provide the following fields in the application_fee_options object when you create an individual payout using Create a payout API:
source_type: Set this toTRANSFER.type: Fee calculation type, eitherFIXEDorPERCENTAGE. You can provide application fee specifications for transfers asFIXED,PERCENTAGE, or both, but no more than one FIXED fee and one PERCENTAGE fee can be specified.- If
typeisFIXED, the following fields are required:amount: A non-negative fee amount.currency: The three-letter ISO-4217 code for the currency of the application fee.
- If
typeisPERCENTAGE, the following field is required:percentage: Represents a direct fee expressed as a number between 0 to 100 and calculated as a percentage of the transaction amount. For example, specifying 0.1 indicates 0.1% of the transaction amount.
- If
The response will contain a detailed breakdown of fees paid for the service in the application_fees object. You can retrieve the application fees anytime using Retrieve a payout API endpoint.
Payouts with conversions
Application fees can be charged on individual payouts with underlying currency conversions (FX Rates) or conversions with a guaranteed quote (FX Quotes).
Provide the application fee specification for each source_type, i.e., CONVERSION and TRANSFER using the application_fee_options object in Create a payout API.
For each source_type, provide the relevant application fee calculation type and fields. For details on what to provide, see Conversions and Payouts application fees.
Each source type (CONVERSION, TRANSFER) can have only one application fee option for each calculation type (FIXED, PERCENTAGE). For example, if the source_type is TRANSFER, you can specify no more than one FIXED fee and one PERCENTAGE fee.
Application fee report
You can use Platform reports API to retrieve a consolidated list of application fees charged to your account. Specify type as APPLICATION_FEE_REPORT in Create a platform report API.
The downloadable report retrieved via Get a platform report API will include the following fields.
| Field | Description |
|---|---|
id | The ID of the application fee. |
amount | The amount of the application fee. |
currency | The currency of the application fee. |
status | The status of the application fee. Possible values: SETTLED, NEW |
source_type | The source transaction type for this application fee, CONVERSION or TRANSFER. |
source_id | The id of the source transaction, e.g. the associated conversion id. |
owner_account_id | The account id that the application fee will settle to. |
description | The description of the application fee. |
created_at | The time at which the application fee was created. |
last_update | The time at which the application fee was last updated. |
application_fee_options | The specification for the application fee. |