Alipay+ DocsAlipay+ Docs

Transaction Detail Report

Overview

Transaction Detail Reports that are provided by Alipay+ to the Acquiring Service Provider (ACQP) include all the transaction details to be cleared in a clearing cycle.

Specifically:

  • Only transactions to be settled, including successful payments and refunds, are included in the Transaction Detail Report.
  • Only the transactions that are completed within the clearing cycle are included in the Transaction Detail Report. The transaction completion time is specified by the transactionTime parameter.

For every clearing cycle, a Transaction Detail Report is created with other reports in the same clearing cycle, such as the Transaction Summary Report and the Fee 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 Transaction Detail 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 transactionItems_<participantId>_<settlementCurrency>_<clearingBatchId>_<participantAgreementId>_<seq>.csv, where:

  • 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.
  • 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.
  • settlementCurrency: the currency that is used in settlement, as agreed in the contract.
  • 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 Transaction Detail Report consists of two parts:

  • The summary section displays the summary information about the transactions, for example, the total number of transactions and net total amount.
  • The details section displays the transaction details, for example, transaction data details.

If no transaction exists in a clearing cycle, the Transaction Detail Report is still generated. The report summary section displays 0 total count and 0 total amount, and the report detail section displays no transaction details.

Structure

Summary section

No.

Parameter

Description

1

totalCount

Required String

The total number of items in the Transaction Detail Report file.

2

fundDirection

Required String

The fund direction. Valid values are:

  • CREDIT: specifies the fund direction from Alipay+ to the ACQP.
  • DEBIT: specifies the fund direction from the ACQP to Alipay+.

3

settlementCurrency

Required String (3)

The currency of the net settlement amount. The value is specified by using the 3-character ISO 4217 currency code.

4

netSettlementAmountValue

Required Integer

The gross settlement amount of all the transactions, excluding the fee settlement 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.

5

transactionCurrency

Optional String (3)

The currency of the net transaction amount. 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. The value is specified by using the 3-character ISO 4217 currency code.

Note: This parameter is empty when no transaction occurs in the clearing cycle or multiple transaction currencies are involved in the clearing cycle.

6

netTransactionAmountValue

Optional Integer

The gross transaction amount of all the transactions, excluding the fee 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.

Note: This parameter is empty when no transaction occurs in the clearing cycle or multiple transaction currencies are involved in the clearing cycle.

7

extendInfo

Optional String (2048)

The 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

counterParticipantId

Required String (64)

The unique ID that is assigned by Alipay+ to identify a Mobile Payment Provider.

For the wallets that are indicated by the value of this parameter, see the table in the overview of MPP capabilities.

4

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 paymentRequestId for a payment, and to that of refundRequestId for a refund.

5

originalTransactionRequestId

Optional String (64)

An identifier for the original transaction.

  • If the value of the transactionType parameter is REFUND, the value of the originalTransactionRequestId parameter is identical to that of the paymentRequestId parameter.
  • If the value of the transactionType parameter is PAYMENT, originalTransactionRequestId is empty.

6

transactionType

Required String

The transaction type. Valid values are:

  • PAYMENTPayment
  • REFUND: Refund

7

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.

8

fundDirection

Required String

The fund direction. Valid values are:

  • CREDIT: specifies the fund direction from Alipay+ to the ACQP.
  • DEBIT: specifies the fund direction from the ACQP to Alipay+.

9

settlementCurrency

Required String (3)

The currency of the settlement amount. The value is specified by using the three-character ISO 4217 currency code.

10

settlementAmountValue

Required Integer

The settlement amount of a transaction. The value of this parameter follows the rules below:

  • The value is calculated in the formula:

settlement amount = transaction amount * FX rate

, where:

    • The transaction amount is specified by the transactionAmountValue parameter in this report.
    • The FX rate is the foreign exchange rate between the settlement currency and the transaction currency. The FX rate is specified by the settlementQuote parameter in the API call of the original transaction. For the payment transaction, the settlementQuote parameter is specified in the notifyPayment API request and the inquiryPayment API response; for the refund transaction, the settlementQuote parameter is specified in the refund API response.
  • 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.

11

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.

12

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.

13

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

14

feeCurrency

Optional String (3)

The currency of the net fee amount. The value is specified by using the 3-character ISO 4217 currency code, and the same as the value of transactionCurrency.

Note: This parameter is only passed if the fee is calculated in the transaction currency.

15

netFeeAmountValue

Optional Integer

The net fee amount of all the fees that are charged for the transaction.

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

feeSettlementCurrency

Optional String (3)

The currency of the net fee settlement 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 settlement currency.

17

netFeeSettlementAmountValue

Optional Integer

The net fee settlement amount of all the clearing fees that are charged for the transaction.

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 settlement currency.

18

extendInfo

Optional String (2048)

The extended information.

Samples

This section contains sample reports for different scenarios.

Payment only

The following sample assumes that the ACQP with an ID of A1234567890 has two payments on 2022-04-19. The payments are made and settled in EUR.

See the following section for details:

  • Summary section: the ACQP gets a settlement fund of 20 EUR in total, as a result of two payments that net 20 EUR in total.
  • Detail section:
    • A payment of 10 EUR is made, which leads to 10 EUR in the settlement amount, and 0.2 EUR in the fee settlement amount for the ACQP.
    • Another payment of the same amount is made and leads to the same result in settlement and fees.

📎transactionItems_A1234567890_EUR_202204190000200000_20210001_000.csv

Payment & refund

The following sample assumes that the ACQP with an ID of A1234567890 has 14 transactions on 2022-04-28. The transactions are made and settled in EUR.

See the following section for details:

  • Summary section: the ACQP gets a settlement fund of 82 EUR in total, as a result of 14 transactions that net 82 EUR in total.
  • Detail section:
    • Seven payments are made, each of 23 EUR. Each payment leads to 0.46 EUR in the fee settlement amount for the ACQP.
    • Seven refunds are made for 5 payments, in different amounts.

📎transactionItems_A1234567890_EUR_202204280000200000_20210000_000.csv

Payment & refund in multiple currencies

The following sample assumes that the ACQP with an ID of A1234567890 has 11 transactions on 2022-01-10. Some transactions are made in MYR, some others are in HKD. All transactions are settled in EUR.

See the following section for details:

  • Summary section: the ACQP gets a settlement fund of 0.5 EUR in total, as a result of 11 transactions.
  • Detail section:
    • 5 payments are made in different amounts in HKD or in MYR.
    • 6 refunds are made for 4 payments. The refunds are also made in different amounts in HKD or in MYR.
    • The fee amounts are too low to be settled in EUR. Therefore, all the fees are 0.

📎transactionItems_A1234567890_EUR_202201101107957472_202109171107900901003800022697_000.csv