Alipay+ DocsAlipay+ Docs

Fee Report

Overview

Fee Reports that are provided by Alipay+ to the Acquiring Service Provider (ACQP) 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.

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, where:

Field Name

Details

participantId

The unique ID that Alipay+ assigns to the ACQP. 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

The 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 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.
  • 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 from Alipay+ to the ACQP.
  • DEBIT: specifies the fee direction 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 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.

  • 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.

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 paymentAmount.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 ACQP pays to Alipay+ for a transaction.

11

feeDirection

Required String

The fee direction. Valid values are:

  • CREDIT: specifies the fee direction from Alipay+ to the ACQP.
  • DEBIT: specifies the fee direction 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 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:

  • 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 parameter in the Transaction Detail Report.
      • The fee rate is determined by your contract with Alipay+.
    • For refund transactions:
      Alipay+ returns the interchange fees to the ACQP 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. 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 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.

Fees for payment only

The following sample is the fee report based on the sample Payment only Transaction Detail Report. The ACQP 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

See the following section for details:

  • Summary section: the ACQP 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.1 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 Transaction Detail Report. The ACQP 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

See the following section for details:

  • Summary section: the ACQP 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.23 EUR as the interchange fee.
    • Seven refunds are made in different amounts. As a result, seven items of interchange fees are returned to the ACQP.

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 Transaction Detail Report. The ACQP 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