# Fee Report

## Overview

Fee Reports that are provided by Alipay+ to the Mobile Payment Providers (MPPs) include the fee details in a clearing cycle.

For every clearing cycle, a Fee Report is created with other reports in the same clearing cycle, such as the Transaction Detail Report and the Transaction Summary Report. The reports are uploaded to a specific directory on the SFTP server. The MPP can download and use them for reconciliation.

### File location and naming convention

The Fee Report is a UTF-8 encoded text file.

In the production environment, the file is saved by default in the directory `/v1/settlements/clearing/<participantId>/<date>`. And in the sandbox environment, the file is saved in the directory `/sandbox/settlements/clearing/<participantId>/<date>`.

The default file name is `feeItems_<participantId>_<settlementCurrency>_<clearingBatchId>_<participantAgreementId>_<seq>.csv`. For the detailed information of each field in the file name, refer to the following table:

| **Field Name** | **Details** |
| --- | --- |
| participantId | The unique ID that Alipay+ assigns to the MPP, also known as the "Partner ID". This field identifies the receiver of the file. |
| date | The date when the report is generated, not the date of the transactions. For example, a report with a date of 20220319 is generated on 2022.03.19. |
| settlementCurrency | The currency that is used in the settlement, as agreed in the contract. This is the same currency as the one that is stated in the Settlement Report. |
| clearingBatchId | Clearing cycle index, used to indicate a unique clearing cycle. A clearing cycle is from 00:00 to 23:59:59, UTC+8. |
| participantAgreementId | The unique ID that is assigned by Alipay+ to identify a settlement agreement between Alipay+ and the MPP. The value of the _participantAgreementId_ parameter is determined by the value of the _participantId_ parameter and the settlement currency used by the MPP. The ID represents the fund flow when MPP performs settlement to Alipay+. |
| seq | The sequence number used as a file index. The field is used when multiple files exist in the clearing cycle. The file index is ordered in the range of `000-999`. |

### Report structure

The Fee Report consists of two parts:

-   Summary section, which displays the summary information about fees, for example, the total number of fee items and the total amount of fees.
-   Detail section, which displays the fee details.

When there is no fee for settlement, the report summary section displays 0 total count and 0 total amount, and the report detail section displays no fee details.

## Structure

### Summary section

| **No.** | **Parameter** | **Description** |
| --- | --- | --- |
| 1 | totalCount | **Required** String The total number of the fee items in the Fee Report. |
| 2 | feeDirection | **Required** String Fee direction. Valid values are: - `CREDIT`: specifies the fee direction that is from Alipay+ to MPP. - `DEBIT`: specifies the fee direction that is from MPP to Alipay+. |
| 3 | feeSettlementCurrency | **Required** String (3) The currency of the net fee settlement amount_._ The currency here is the same as the settlement currency of the transactions in the clearing cycle. The value is specified by using the 3-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. |
| 4 | netFeeSettlementAmountValue | **Required** Integer The fee amount that is the net sum of the fee settlement amount value (the _feeSettlementAmountValue_ parameter in the detail section). The value is provided in the smallest unit of the corresponding currency and rounded with [Banker's rounding](bank_rounding). For example, if the currency is USD and the amount is $1.00, the value of this parameter is 100; if the currency is JPY and the amount is ￥1, the value of this parameter is 1. If the fee settlement amount is less than the smallest unit of the fee settlement currency, the value of this parameter will be 0. Value range: 0 - unlimited. |
| 5 | feeCurrency | **Optional** String (3) The currency of the net fee amount. The value is specified by using the 3-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. > **Note**: This parameter is only passed if the fee is calculated in the transaction currency. |
| 6 | netFeeAmountValue | **Optional** Integer The fee amount that is the net sum of the fee amount value (the feeAmountValue parameter in the detail section). The value is provided in the smallest unit of the corresponding currency and rounded with [Banker's rounding](bank_rounding). For example, if the currency is USD and the amount is $1.00, the value of this parameter is 100; if the currency is JPY and the amount is ￥1, the value of this parameter is 1. If the fee settlement amount is less than the smallest unit of the fee settlement currency, the value of this parameter will be 0. Value range: 0 - unlimited. > **Note**: This parameter is only passed if the fee is calculated in the transaction currency. |
| 7 | extendInfo | **Optional** String (2048) Extended information. |

### Detail section

| **No.** | **Parameter** | **Description** |
| --- | --- | --- |
| 1 | clearingBatchId | **Required** String (32) The unique ID that is assigned by Alipay+ to identify a clearing cycle. A clearing cycle is from 00:00 to 23:59:59, UTC+8. |
| 2 | participantId | **Required** String (64) The unique ID that is assigned by Alipay+ to identify an MPP. |
| 3 | transactionRequestId | **Required** String (64) The unique ID that is assigned by Alipay+ to identify a transaction. - For a payment, the value of this parameter is identical to that of the _paymentRequestId_ parameter. - For a refund, the value of this parameter is identical to that of _the refundRequestId_ parameter. |
| 4 | originalTransactionRequestId | **Optional** String (64) An identifier for the original payment order of a refund. - For a payment, the value of this parameter is empty. - For a refund, the value of this parameter is identical to that of the _paymentRequestId_ parameter. |
| 5 | transactionType | **Required** String Transaction type. Valid values are: - `PAYMENT`: Payment - `REFUND`: Refund |
| 6 | transactionTime | **Required** Datetime The date and time when the transaction reaches a final state of success or failure. The transaction time can be obtained from the _paymentTime_ parameter in the **notifyPayment** API or the **inquiryPayment** API, or the _refundTime_ parameter in the **refund** API. The value follows the [ISO 8601 standard](https://www.iso.org/iso-8601-date-and-time-format.html). |
| 7 | transactionCurrency | **Required** String (3) The currency of the transaction amount. The value is specified by using the 3-character [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. The currency here is the same as the currency of the transactions in the clearing cycle, which is the value of the _payToAmount.currency_ parameter in the **pay** API. |
| 8 | transactionAmountValue | **Required** Integer The transaction amount. The value is provided in the smallest unit of the corresponding currency. For example, if the currency is USD and the amount is $1.00, the value of this parameter is 100; if the currency is JPY and the amount is ￥1, the value of this parameter is 1. Value range: 0 - unlimited. |
| 9 | feeId | **Required** String (64) The unique ID that is assigned by Alipay+ to identify a fee. |
| 10 | feeType | **Required** String The fee type. Valid values are: - `INTERCHANGE_FEE`: interchange fee, also known as interpartner fee, the fee that the ACQP pays to the MPP for a transaction. - `SERVICE_FEE`: service fee, the fee that the MPP pays to Alipay+ for a transaction. |
| 11 | feeDirection | **Required** String The fee direction. Valid values are: - `CREDIT`: specifies the fee direction that is from Alipay+ to MPP. - `DEBIT`: specifies the fee direction that is from MPP to Alipay+. |
| 12 | feeSettlementCurrency | **Required** String (3) The currency of the net fee settlement amount_._ The currency here is the same as the settlement currency of the transactions in the clearing cycle, which is the value of the _settlementStrategy.settlementCurrency_ parameter in the **pay** API. The value is specified by using the 3-character [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. |
| 13 | feeSettlementAmountValue | **Required** Integer The fee settlement amount of a transaction. The value of this parameter follows the rules below: - For different types of transactions, the value of this parameter is calculated in different formulas: - For payment transactions: fee settlement amount = settlement amount of the payment \* fee rate , where: - The settlement amount of the payment is specified by the _settlementAmountValue_ in the Transaction Detail Report. - The fee rate is determined by your contract with Alipay+. - For refund transactions: The MPP returns the interchange fees to Alipay+ in proportion to the refund. fee settlement amount = \[settlement amount of the refund\] _/_ \[settlement amount of the original payment\] \* \[fee settlement amount of the original payment\] , where - The settlement amounts of the refund and of the original payment are specified by the _settlementAmountValue_ parameters respectively in the Transaction Detail Report. - The fee settlement amount of the original payment is specified by the corresponding _feeSettlementAmountValue_ parameter in this report. - The value is provided in the smallest unit of the corresponding currency and rounded with [Banker's rounding](bank_rounding). For example, if the currency is USD and the amount is $1.00, the value of this parameter is 100; if the currency is JPY and the amount is ￥1, the value of this parameter is 1. If the fee settlement amount is less than the smallest unit of the fee settlement currency, the value of this parameter will be 0. Value range: 0 - unlimited. |
| 14 | feeCurrency | **Optional** String (3) The currency of the fee amount. The value is specified by using the 3-character [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code and is the same as the value of _transactionCurrency_. > **Note**: This parameter is only passed if the fee is calculated in the transaction currency. |
| 15 | feeAmountValue | **Optional** Integer The fee amount charged for a transaction, calculated according to the transaction amount value (_transactionAmountValue_) in the Transaction Detail Report. The value is provided in the smallest unit of the corresponding currency and rounded with [Banker's rounding](bank_rounding). For example, if the currency is USD and the amount is $1.00, the value of this parameter is 100; if the currency is JPY and the amount is ￥1, the value of this parameter is 1. If the fee settlement amount is less than the smallest unit of the fee settlement currency, the value of this parameter will be 0. Value range: 0 - unlimited. > **Note**: This parameter is only passed if the fee is calculated in the transaction currency. |
| 16 | extendInfo | **Optional** String (2048) The extended information. |

## Samples

This section contains sample reports for different scenarios.

### Fees for payment only

The following sample is the fee report based on the sample [Payment only](trans_detail#ubRy9) detail report. The MPP with an ID of `A1234567890` has **four** fee items on 2022-04-19. The fees are settled in EUR.

You can view the sample in the following window or download the sample file: 

[📎feeItems\_A1234567890\_EUR\_202204190000200000\_20210001\_000.csv](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/attachments/yuque/0/2023/csv/12884741/1687336779335-73917151-d421-4c9d-bd3c-043a7e4e1240.csv)

[feeItems\_A1234567890\_EUR\_202204190000200000\_20210001\_000.csv](https://idocs.alipay.com/file-preview?param=storage%2Fidocs87c36dc8dac653c1%2Fyuque%2Fattachments%2Fyuque%2F0%2F2023%2Fcsv%2F12884741%2F1687336761117-f20aeb6a-33b0-4c06-aca1-974d229ad3a1.csv)

See the following section for details:

-   **Summary section**: the MPP gets a settlement fund of **0.4** **EUR**, as a result of **four** fee items.
-   **Detail section**:

-   A **payment** of **10 EUR** is made, which leads to **0.1 EUR** in the fee settlement amount as the service fee, and **0.3** **EUR** as the interchange fee.
-   Another **payment** is made in the same amount and leads to the same result in the fees.

### Fees for payment & refund

The following sample is the fee report based on the sample [Payment & refund](trans_detail#AukhT) Transaction Detail Report. The MPP with an ID of `A1234567890` has **28** fee items on 2022-04-28. The fees are settled in EUR.

You can view the sample in the following window or download the sample file: 

[📎feeItems\_A1234567890\_EUR\_202204280000200000\_20210000\_000.csv](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/attachments/yuque/0/2023/csv/12884741/1687336827537-7007a067-6ef1-4932-8459-b91f093946b9.csv)

[feeItems\_A1234567890\_EUR\_202204280000200000\_20210000\_000.csv](https://idocs.alipay.com/file-preview?param=storage%2Fidocs87c36dc8dac653c1%2Fyuque%2Fattachments%2Fyuque%2F0%2F2023%2Fcsv%2F12884741%2F1687336806598-69890690-7f23-4ae0-87d5-8e920e3b6d6f.csv)

See the following section for details:

-   **Summary section**: the MPP gets a fee settlement fund of **2.43 EUR** in total, as a result of **28** fee items.
-   **Detail section**:

-   **Seven payments** are made in **EUR**, each of **23 EUR**. Each payment leads to **0.23 EUR** in the fee settlement amount as the service fee, and **0.69** **EUR** as the interchange fee.
-   **Seven refunds** are made in different amounts. As a result, **seven** items of interchange fees in respective amounts are returned to Alipay+.

### Fees are too low to be calculated (Payment & refund in multiple currencies)

The following sample is the fee report based on the sample [Payment & refund in multiple currencies](trans_detail#qsjBf) Transaction Detail Report. The MPP with an ID of `A1234567890` has **22** fee items totaling **0 EUR** on 2022-01-10. This happens when the fee settlement amount is too low to be calculated in one smallest unit of the settlement currency. All fees are settled in EUR.

You can view the sample in the following window or download the sample file: 

[📎feeItems\_A1234567890\_EUR\_202201101107957472\_202109171107900901003800022697\_000.csv](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/attachments/yuque/0/2023/csv/12884741/1687336882506-01f09dda-d834-4881-bca9-56c08d93cce0.csv)

[feeItems\_A1234567890\_EUR\_202201101107957472\_202109171107900901003800022697\_000.csv](https://idocs.alipay.com/file-preview?param=storage%2Fidocs87c36dc8dac653c1%2Fyuque%2Fattachments%2Fyuque%2F0%2F2023%2Fcsv%2F12884741%2F1687336847849-4438815b-1068-4008-a64c-f57a96ebc10e.csv)