Fee Report

Overview

Fee Reports that are provided by Alipay+ to the Acquiring Service Provider (ACQP) include the fee details in a clearing cycle. The Fee Report is provided in the file format, and generated together with a Transaction Summary Report of the clearing cycle. This Fee Report file is uploaded to a specific directory in SFTP. The ACQP needs to download and use it for reconciliation.

File location and naming convention

The Fee Report file is a text file in the UTF-8 encoding. By default, this file is saved in the directory /v1/settlements/clearing/<participantId>/<date>, and default file name is feeItems_<participantId>_<settlementCurrency>_<clearingBatchId>_<participantAgreementId>_<seq>.csv, where:

participantId: the unique ID that Alipay+ issues to the ACQP.
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: is the unique ID that is assigned by Alipay+ to identify a settlement agreement 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 (and separately allocated for AlipayCN). The ID represents the fund flow when Alipay+ performs settlement to the ACQP.
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, which 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.	Field	Description
1	totalCount	Required String Total number of items in the Fee Report file.
2	feeDirection	Required String Fee direction. Valid values are: `CREDIT`: specifies the fee direction that is from Alipay+ to the ACQP `DEBIT`: specifies the fee direction that is from the ACQP 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, which is the value of the settlementStrategy.settlementCurrency parameter in the pay API. The value is specified by using the three-character ISO 4217 currency code.
4	netFeeSettlementAmountValue	Required String (16) The fee amount that is the net sum of the fee settlement amount value (the feeSettlementAmountValue parameter in the detail section).
5	feeCurrency	Optional String (3) The currency of the net fee amount. The value is specified by using the three-character ISO 4217 currency code.
6	netFeeAmountValue	Optional String (16) 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.
7	extendInfo	Optional String (2048) Extended information.

Detail section

No.	Field	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. For a payment, the value of this field is identical to that of paymentRequestId. For a refund, the value of this field is identical to that of refundRequestId.
4	originalTransactionRequestId	Optional String (64) An identifier for the original transaction. If the value of the transactionType field is `REFUND`, this field is identical to that of paymentRequestId. If the value of the transactionType field is `PAYMENT`, this field is empty.
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 of the notifyPayment API or inquiryPayment API, or the refundTime parameter of the refund 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 three-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 paymentAmount.currency parameter in the pay API.
8	transactionAmountValue	Required String (16) Transaction amount. The value is provided in the smallest unit of the corresponding currency.
9	feeId	Required String (64) The unique ID that is assigned by Alipay+ to identify a fee.
10	feeType	Required String Fee type. Valid values are: `INTERCHANGE_FEE`: Interchange fee `SERVICE_FEE`: Service fee
11	feeDirection	Required String Fee direction. Valid values are: `CREDIT`: specifies the fee direction that is from Alipay+ to the ACQP. `DEBIT`: specifies the fee direction that is from the ACQP 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 three-character ISO 4217 currency code.
13	feeSettlementAmountValue	Required String (16) The fee settlement amount of the transaction, calculated according to the settlement amount value (settlementAmountValue) in the Clearing Transaction Report. The value is provided in the smallest unit of the corresponding currency. If the fee settlement amount is less than the smallest unit of the fee settlement currency, the value of this parameter will be 0.
14	feeCurrency	Optional String (3) The currency of the fee amount. The value is specified by using the three-character ISO 4217 currency code and is the same as the value of transactionCurrency.
15	feeAmountValue	Optional String (16) The fee amount charged for a transaction, calculated according to the transaction amount value (transactionAmountValue) in the Clearing Transaction Report. The value is provided in the smallest unit of the corresponding currency.
16	extendInfo	Optional String (2048) Extended information.

Sample

Use Case 1

The following sample assumes that the ACQP with an ID of 102xxxxxxxxxxxx0001 has 4 fee items on December 25, 2018, and then Alipay+ provides a fee report to the ACQP on December 26, 2018.

See the following section for details:

Summary section: the total fee amount for the ACQP is 1.25 USD, as a result of 4 fee items.
Detail section:

1 payment is made in 180 KRW, which leads to 0.5 USD settlement fee amount as the service fee.
1 payment is made in 180 KRW, which leads to 1 USD settlement fee amount as the interchange fee.
1 refund is made in 90 KRW, which leads to 0.00 USD settlement fee amount as the service fee.
1 refund is made in 90 KRW, which leads to -0.5 USD settlement fee amount as the interchange fee.

Note: As the fee is calculated according to the settlement currency and settlement amount, the fields of feeCurrency and netFeeAmountValue in both the summary and detail sections are empty.

copy
totalCount,feeDirection,feeSettlementCurrency,netFeeSettlementAmountValue,feeCurrency,netFeeAmountValue,extendInfo
4,DEBIT,USD,100,,,
clearingBatchId,participantId,transactionRequestId,originalTransactionRequestId,transactionType,transactionTime,transactionCurrency,transactionAmountValue,feeId,feeType,feeDirection,feeSettlementCurrency,feeSettlementAmountValue,feeCurrency,feeAmountValue,extendInfo
201812261102104****,102218800000000****,10277574507****,,PAYMENT,2018-12-25T10:00:00+08:30,KRW,18000,2018122519074101000000000212031,SERVICE_FEE,DEBIT,USD,50,,,
201812261102104****,102218800000000****,10277574507****,,PAYMENT,2018-12-25T10:00:00+08:30,KRW,18000,2018122519074101000000000212032,INTERCHANGE_FEE,DEBIT,USD,100,,,
201812261102104****,102218800000000****,10277574507****,10277574507****,REFUND,2018-12-25T10:00:00+08:30,KRW,9000,201812251907410100000000021****,SERVICE_FEE,DEBIT,USD,0,,,
201812261102104****,102218800000000****,10277574507****,10277574507****,REFUND,2018-12-25T10:00:00+08:30,KRW,9000,201812251907410100000000021****,INTERCHANGE_FEE,CREDIT,USD,50,,,

Use case 2

The following sample assumes that the ACQP with an ID of 102xxxxxxxxxxxx0001 has no transactions on December 25, 2018. Alipay+ provides a fee report to the ACQP on December 26, 2018.

In this case,

In the summary section, the total count is 0; the fund direction is the default value, DEBIT; the fee settlement currency is still USD, and the gross settlement amount value is0. All other parameters are empty.
The detail section is empty.

copy
totalCount,feeDirection,feeSettlementCurrency,netFeeSettlementAmountValue,feeCurrency,netFeeAmountValue,extendInfo
0,DEBIT,USD,0,,,
clearingBatchId,participantId,transactionRequestId,originalTransactionRequestId,transactionType,transactionTime,transactionCurrency,transactionAmountValue,feeId,feeType,feeDirection,feeSettlementCurrency,feeSettlementAmountValue,feeCurrency,feeAmountValue,extendInfo