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

      Transaction Items

      Transaction Items file is used by Alipay to provide merchants with all successful transaction details on T day, which is generated on T + 1 day. The transaction details file will be uploaded to the agreed directory in the specified SFTP for merchants to download and use.


      #Samples

      Case 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,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,orderDescription,paymentMethodType,pspName,transactionType,paymentTime,productCode,transactionAmountValue,transactionCurrency
      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
      <END>


      Case 2: There is no transaction on December 25, 2018. On 2018/12/26, 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,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,orderDescription,paymentMethodType,pspName,transactionType,paymentTime,productCode,transactionAmountValue,transactionCurrency
      <END>


      #Structure

      #File head

      N/A


      #File body

      This section gives an overview of the parameters in file body. See the following table for details:

      Field

      Description

      customerId

      MANDATORY String (64)

      The unique ID that is assigned by Alipay to identify a merchant

      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.

      originalTransactionId

      OPTIONAL String (64)

      An identifier for the original transaction.

      • When transactionType is PAYMENT, CANCEL, AUTHORIZATION, or VOID, the value of this field is null.
      • 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.

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

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

      orderDescription

      OPTIONAL String (256)

      Order description

      paymentMethodType

      MANDATORY String (32)

      Payment method type of the payment that is processed.

      For auto debit payments and cashier payments, possible values are:

      • TRUEMONEY
      • ALIPAY_HK
      • TNG
      • ALIPAY_CN
      • GCASH
      • DANA
      • BKASH
      • EASYPAISA
      • KAKAOPAY
      • CONNECT_WALLET

      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 payment method provider. For more details, see pspName.

      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 TransactionType

      Transaction type. Possible values are:

      • PAYMENT
      • REFUND
      • CANCEL
      • AUTHORIZATION
      • CAPTURE
      • VOID

      paymentTime

      MANDATORY String (64)

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

      productCode

      MANDATORY ProductCodeType

      The type of the payment product that is contracted between Alipay and the merchant. Possible 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 the smallest unit of the corresponding currency

      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, this field is null.


      #More information

      This section gives additional information about certain parameters and the Settlement Items file. See the following list for details:

      • The transaction details file is a text file encoded in UTF-8. The file storage path defaults to /v1/settlements/<customerId>/<transactionDate>/ and the file name defaults to transactionItems_<transactionDate>_<seq>.csv. The variable description in the file name is as follows:
        • customerId: the identity assigned by Alipay for merchants.
        • transactionDate: the date of transaction.
        • seq: file serial number. When there are multiple transaction details in the same transaction cycle, each detail file will be increased from 000 as needed, up to 999.
      • The Transaction Items file is divided into two parts: Transaction details, and the file terminator. The file terminator <END> appears in the last line of the file as the file end flag.