Fee Report
Overview
Fee Reports that are provided by Alipay+ to the Acquiring Service Provider (ACQP) and 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 ACQP can download and use them for reconciliation.
File location and naming convention
The Fee Report is a UTF-8 encoded text file. By default, this file is saved in the directory /v1/settlements/clearing/<participantId>/<date>
, and the default file name is feeItems_<participantId>_<settlementCurrency>_<clearingBatchId>_<participantAgreementId>_<seq>.csv
, where:
- participantId: the unique ID that Alipay+ issues to the ACQP, 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 settlement, as agreed in the contract. This is the same currency as the one that is stated in the settlement report file.
- 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 the settlement agreements between Alipay+ and the ACQP. The value of the participantAgreementId parameter is determined by the value of the participantId parameter and the settlement currency used by the ACQP. The ID represents the fund flow when ACQP 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.
- Details section, which displays the fee details and provides detailed fee data.
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:
|
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, which is the value of the payerAmount.currency parameter in the createOriginalCredit API. The value is specified by using the 3-character ISO 4217 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. 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 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. 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 ACQP. |
3 | transactionRequestId | Required String (64) The unique ID that is assigned by the ACQP to identify a transaction. The value of this parameter is identical to that of originalCreditRequestId for an OCT. |
4 | originalTransactionRequestId | Optional String (64) An identifier for the original transaction. For OCT transactions, this parameter is empty. |
5 | transactionType | Required String The transaction type. The valid value is |
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 originalCreditTime parameter in the notifyOriginalCredit API or the inquireOriginalCredit API. The value follows the ISO 8601 standard. |
7 | transactionCurrency | Required String (3) The currency of the transaction amount. The value is specified by using the 3-character 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 payerAmount.currency parameter in the createOriginalCredit 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. The valid value is |
11 | feeDirection | Required String The fee direction. Valid values are:
|
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 payerAmount.currency parameter in the createOriginalCredit API. The value is specified by using the 3-character ISO 4217 currency code. |
13 | feeSettlementAmountValue | Required Integer The fee settlement amount of a transaction. The value of this parameter follows the rules below:
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 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. 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.
OCTs in one currency
The following sample is the fee report based on the sample OCTs in one currency detail report. The ACQP with an ID of A1234567890
has two fee items on 2022-04-19. The fees are settled in EUR.
See the following section for details:
- Summary section: the ACQP is to be debited a settlement fund of 0.2 EUR, as a result of two fee items.
- Detail section:
- An OCT of 10 EUR is made, which leads to 0.1 EUR in the fee settlement amount as the service fee.
- Another OCT is made in the same amount and leads to the same result in the fees.
📎feeItems_A1234567890_EUR_202204190000200000_20210001_000.csv
OCTs in multiple currencies
The following sample is the fee report based on the sample OCTs in multiple currencies detail report. The ACQP with an ID of A1234567890
has five fee items on 2022-01-10. The fees are settled in EUR.
See the following section for details:
- Summary section: the ACQP gets a fee settlement fund of 0 EUR in total, as a result of five fee items.
- Detail section:
- Four OCTs are made in MYR, each of 1 MYR.
- One OCT of 1 HKD is made.
- The fee amounts are too low to be settled in EUR. Therefore, all the fees are 0.
📎feeItems_A1234567890_EUR_202201101107957472_202109171107900901003800022697_000.csv