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.

The Transaction Detail Report is provided in the file format, and is generated with a Transaction Summary Report of the clearing cycle. The Transaction Detail 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 Transaction Detail 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 the default file name is transactionItems_<participantId>_<settlementCurrency>_<clearingBatchId>_<participantAgreementId>_<seq>.csv, where:

participantId: the unique ID that Alipay+ assigns to the ACQP. The 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: clearing cycle index, used to indicate a unqiue 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: 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 Transaction Detail Report consists of two parts:

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

If no transaction exists in a clearing cycle, the Transaction Detail Report is still generated with the Transaction Summary Report. 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.	Field	Description
1	totalCount	Required String Total number of items in the Transaction Detail Report file.
2	fundDirection	Required String Fund direction. Valid values are: `CREDIT`: specifies the fund direction that is from Alipay+ to the ACQP. `DEBIT`: specifies the fund direction that is from the ACQP to Alipay+
3	settlementCurrency	Required String (3) The currency of the net settlement amount. The value is specified by using the three-character ISO 4217 currency code.
4	netSettlementAmountValue	Required String (16) The gross settlement amount, including the fee settlement amount. The value is provided in the smallest unit of the corresponding currency.
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 three-character ISO 4217 currency code. Note: This field is empty when no transaction occurs in the clearing cycle or multiple transaction currencies are involved in the clearing cycle.
6	netTransactionAmountValue	Optional String (16) Net transaction amount. The value is provided in the smallest unit of the corresponding currency. Note: This field 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) 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	counterParticipantId	Required String (64) The unique ID that is assigned by Alipay+ to identify a Mobile Payment Provider.
4	transactionRequestId	Required String (64) The unique ID that is assigned by the ACQP to identify a transaction. The value of this field 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 field is `REFUND`, this field is identical to that of paymentRequestId. If the value of the transactionType field is `PAYMENT`, this field is empty.
6	transactionType	Required String Transaction type. Valid values are: `PAYMENT`: Payment `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 Fund direction. Valid values are: `CREDIT`: specifies the fund direction that is from Alipay+ to the ACQP `DEBIT`: specifies the fund direction that is 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 String (16) The amount in the settlement currency. The value is provided in the smallest unit of the corresponding currency.
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 String (16) Transaction amount. The value is provided in the smallest unit of the corresponding currency.
13	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+
14	feeCurrency	Optional String (3) The currency of the net fee amount. The value is specified by using the three-character ISO 4217 currency code, and the same as the value of transactionCurrency.
15	netFeeAmountValue	Optional String (16) 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.
16	feeSettlementCurrency	Optional String (3) The currency of the net fee settlement amount. The value is specified by using the three-character ISO 4217 currency code.
17	netFeeSettlementAmountValue	Optional String (16) The net fee settlement amount of all the clearing fees that are charged for the transaction.
18	extendInfo	Optional String (2048) Extended information.

Sample

Use case 1

The following sample assumes that the ACQP with an ID of 102218800000000**** has 2 transactions on December 25, 2018, and then Alipay+ provides a Transaction Detail Report to the ACQP on December 26, 2018. In the sample, the user pays in KRW, and the ACQP settles in USD.

See the following section for details:

Summary section: the ACQP gets a settlement fund of 7.25 USD in total, as a result of 2 transactions that net 90 KRW in total.
Detail section:

1 payment is made in 180 KRW, which leads to 15 USD in the settlement amount, and 0.5 USD in the fee settlement amount for the ACQP.
1 refund is made in 90 KRW, which leads to -7.5 USD in the settlement amount, and -0.25 USD in the fee settlement amount for the ACQP.

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

copy

totalCount,fundDirection,settlementCurrency,netSettlementAmountValue,transactionCurrency,netTransactionAmountValue,extendInfo
2,CREDIT,USD,725,KRW,9000,
clearingBatchId,participantId,counterParticipantId,transactionRequestId,originalTransactionRequestId,transactionType,transactionTime,fundDirection,settlementCurrency,settlementAmountValue,transactionCurrency,transactionAmountValue,feeDirection,feeCurrency,netFeeAmountValue,feeSettlementCurrency,netFeeSettlementAmountValue,extendInfo
201812261102104****,102218800000000****,102218800000000****,10277574507****,,PAYMENT,2018-12-25T10:00:00+08:30,CREDIT,USD,1500,KRW,18000,DEBIT,,,USD,50,
201812261102104****,102218800000000****,102218800000000****,10277574507****,10277574507****,REFUND,2018-12-25T10:00:00+08:30,DEBIT,USD,750,KRW,9000,CREDIT,,,USD,25,

Use case 2

The following sample assumes that the ACQP with an ID of 102xxxxxxxxxxxx0001 has no transactions on December 25, 2018. Even though no transaction occurs, Alipay+ still provides the Transaction Detail Report to the ACQP on December 26, 2018.

copy

totalCount,fundDirection,settlementCurrency,netSettlementAmountValue,transactionCurrency,netTransactionAmountValue,extendInfo
0,CREDIT,USD,0,,,
clearingBatchId,participantId,counterParticipantId,transactionRequestId,originalTransactionRequestId,transactionType,transactionTime,fundDirection,settlementCurrency,settlementAmountValue,transactionCurrency,transactionAmountValue,feeDirection,feeCurrency,netFeeAmountValue,feeSettlementCurrency,netFeeSettlementAmountValue,extendInfo

Use case 3

When multiple transaction currencies are involved in the clearing cycle, the fields of transactionCurrency and netTransactionAmountValue in the summary section are empty.

See the following section for details:

Summary section: the ACQP gets a settlement fund of 1680 USD in total, as a result of 2 transactions, one in HKD, and one in THB.
Detail section:

1 payment is made in 7762.1 HKD, which leads to 1000 USD in the settlement amount for the ACQP, the fee settlement amount is 160 USD.
1 payment is made in 31250 THB, which leads to 1000 USD in the settlement amount for the ACQP, the fee settlement amount is 160 USD.

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

copy

totalCount,fundDirection,settlementCurrency,netSettlementAmountValue,transactionCurrency,netTransactionAmountValue,extendInfo
2,CREDIT,USD,168000,,,
clearingBatchId,participantId,counterParticipantId,transactionRequestId,originalTransactionRequestId,transactionType,transactionTime,fundDirection,settlementCurrency,settlementAmountValue,transactionCurrency,transactionAmountValue,feeDirection,feeCurrency,netFeeAmountValue,feeSettlementCurrency,netFeeSettlementAmountValue,extendInfo
201812261102104****,102218800000000****,102218800000000****,10277574507****,,PAYMENT,2021-05-12T10:12:17+08:00,CREDIT,USD,100000,HKD,776210,DEBIT,,,USD,16000,
201812261102104****,102218800000000****,102218800000000****,10277574507****,,PAYMENT,2021-05-12T10:12:17+08:00,CREDIT,USD,100000,THB,3125000,DEBIT,,,USD,16000,