Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

Transaction Items

The Transaction Items report is used by Alipay to provide merchants with all the successful transaction details on T day, and is generated on T + 1 day.

Report path and name

The transaction details report is a text file encoded in UTF-8 and is uploaded to the agreed directory in SFTP for merchants to download and use. The file storage path defaults to /v1/settlements/<merchantIdByAcquirer>/<transactionDate>/ plus the file name. The file name is transactionItems_<transactionDate>_<seq>.csv:

  • merchantIdByAcquirer: the identity assigned by Alipay for merchants.
  • transactionDate: the date of transaction.
  • seq: the file serial number.

Report fields

The Transaction Items file is divided into two parts: the transaction details and file ending. The file ending <END> appears in the last line of the file as the file end flag. The transaction details are illustrated by several fields and the corresponding values. The following table shows the details of the fields that appear in the report body:

Field

Description

customerId

MANDATORY String (64)

The unique ID that is assigned by the acquirer to identify a merchant.

acquirer

MANDATORY String (64)

The name of the acquirer that processes the transactions.

The acquirer here specifically means the acquirer that provides acquiring and funds settlement services for the merchant.

acquirerReferenceNo

OPTIONAL String (64)

The unique ID assigned by the non-Alipay acquirer for the transaction.

Specify this parameter when the transaction is settled by the non-Alipay acquirer. If the acquirer is Alipay, the transaction ID is identical to transactionId.

referenceMerchantId

OPTIONAL String (64)

The unique ID of the merchant that directly provides services or goods to users, assigned by the corresponding merchant. 

Note:

The value of this field needs to be the same as that of the referenceMerchantId field in the original payment or authorization request for all other transaction types.

referenceStoreId

OPTIONAL String (64)

The unique ID of the store that belongs to the merchant, assigned by the corresponding merchant.

transactionId

MANDATORY String (64)

The unique ID that is assigned by Alipay to identify a transaction. The value of this field follows these rules:

  • When transactionType is PAYMENT, CANCEL, or AUTHORIZATION, the value of this field is identical to that of paymentId.
  • When transactionType is CAPTURE, the value of this field is identical to that of captureId.
  • When transactionType is REFUND, the value of this field is identical to that of refundId.
  • When transactionType is DISPUTE, the value of this field is identical to that of disputeId.

originalTransactionId

OPTIONAL String (64)

An identifier for the original transaction.

  • When transactionType is PAYMENT, CANCEL, or AUTHORIZATION, the value of this field is empty.
  • When transactionType is VOID, the value of this field is identical to paymentId of the original authorization.
  • When transactionType is REFUND, the value of this field is identical to paymentId of the original payment or authorization.
  • When transactionType is CAPTURE, the value of this field is identical to paymentId of the original authorization.
  • When transactionType is DISPUTE, the value of this field is identical to that of paymentId of the original authorization.

transactionRequestId

MANDATORY String (64)

The unique ID that is assigned by the merchant to identify a transaction request. The value of this field is identical to the value of paymentRequestId for a payment, or the value of refundRequestId for a refund.

When transactionType is DISPUTE, the value of this field is empty.

referenceTransactionId

OPTIONAL String (64)

The unique ID assigned by the merchant that directly provides services or goods to users, to identify a transaction. The value of this field is identical to that of referenceOrderId for a payment.

When transactionType is CANCEL, CAPTURE, or DISPUTE, the value of this field is empty. 

orderDescription

OPTIONAL String (256)

The description of the order. 

paymentMethodType

MANDATORY String (64)

Payment method type of the payment that is processed. See Payment methods to check the valid values.

Note:

The value of this field needs to be the same as that of the paymentMethodType field in the original payment or authorization request for all other transaction types.

pspName

OPTIONAL String (64)

Name of the Alipay+ Mobile Payment Provider, such as GCash.

Note:

The value of this field needs to be the same as that of the pspName field in the original payment or authorization request for all other transaction types.

transactionType

MANDATORY String

Transaction type. Possible values are:

  • PAYMENT: Indicates a payment process.
  • REFUND: Indicates a refund process.
  • CANCEL: Indicates a cancellation process.
  • AUTHORIZATION: Indicates an authorization process.
  • CAPTURE: Indicates a capture process.
  • VOID: Indicates a void authorization.
  • DISPUTE: Indicates a dispute process.

paymentTime

MANDATORY String (64)

The date and time when the corresponding transaction reaches a final status of success, in the format of YYYY-MM-DDTHH:MM:SS+hh:mm as defined in ISO 8601.

productCode

MANDATORY String

The type of payment product that is contracted between Alipay and the merchant. Valid values are:

  • AGREEMENT_PAYMENT: indicates the auto debit payment
  • IN_STORE_PAYMENT: indicates the in-store payment
  • CASHIER_PAYMENT: indicates the cashier payment

Note:

The value of this field needs to be the same as that of the productCode field in the original payment or authorization request for all other transaction types.

transactionAmountValue

MANDATORY String (16)

The transaction amount in major units of the corresponding currency (For example, dollars for USD, and yen for JPY).

transactionCurrency

MANDATORY String (3)

The currency of transactionAmountValue, specified by a 3-letter currency code as defined in ISO 4217.

originalTransactionRequestId

OPTIONAL String (64)

The original payment request ID of the transaction when the transaction type is REFUND, CANCEL, or CAPTURE. Otherwise, the value of this parameter is empty.

installmentsNum

OPTIONAL String (8)

Indicates the number of installment payments.

issuingCountry

OPTIONAL String (2)

The issuing country or region of the card. The parameter is a 2-letter country or region code that follows the ISO 3166 Country Codes standard.

This parameter is specified when paymentMethodType is CARD.

cardBrand

OPTIONAL String (256)

The brand of the card.

This parameter is specified when paymentMethodType is CARD.

funding

OPTIONAL String (6)

The funding type of the card. Valid values are:

  • CREDIT: indicates a credit card.
  • DEBIT: indicates a debit card.

This parameter is specified when paymentMethodType is CARD.

Report samples

Sample 1

On the trading day of December 25, 2018, the merchant with an ID of 1022188000000000001 has two transactions, one for a payment and the other for a refund.

  • Information about the payment:
    • paymentId: 2018122519074101000000000112612, which is also the value of transactionId.
    • paymentAmount: 18000 KRW (transactionAmountValue) for payment.
  • Information about the refund:
    • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
    • refundAmount: 9000 KRW (transactionAmountValue) for refund.

On 2018/12/26, Alipay generates a CSV file with a file name transactionItems_20181225_000.csv. In this case, the merchant customer ID is 1022188000000000001. The file path is /v1/settlements/1022188000000000001/20181225/transactionItems_20181225_000.csv.

The transaction details are as follows:

copy
customerId,acquirer,acquirerReferenceNo,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,orderDescription,paymentMethodType,pspName,transactionType,paymentTime,productCode,transactionAmountValue,transactionCurrency,originalTransactionRequestId,issuingCountry,cardBrand,funding
1022188000000000001,,,,,2018122519074101000000000112612,,20190326L648423000404,,,KAKAOPAY,KaKaoPay,PAYMENT,2018-12-25T10:00:00+08:30,AGREEMENT_PAYMENT,18000,KRW,,,,,
1022188000000000001,,,,,2018122519074102000000000041675,2018122519074101000000000112612,20190326L648423000404,,,KAKAOPAY,KaKaoPay,REFUND,2018-12-25T10:00:00+08:30,AGREEMENT_PAYMENT,-9000,KRW,20190326L648423000404,,,,
<END>

Sample 2

There is no transaction on December 25, 2018. On December 26, 2018, Alipay generates a CSV file with a file name of transactionItems_20181225_000.csv.

The contents of the transaction details file are as follows:

copy
customerId,acquirer,acquirerReferenceNo,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,orderDescription,paymentMethodType,pspName,transactionType,paymentTime,productCode,transactionAmountValue,transactionCurrency,originalTransactionRequestId,issuingCountry,cardBrand,funding
<END>