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

      Settlement Items

      Settlement Items file is used by Alipay to provide merchants with settlement details in a settlement cycle. The settlement details are provided in a document form and are generated with the summary file of the settlement cycle. The settlement details file is to be uploaded to a specified directory in SFTP for merchants to download and use.


      #Sample

      Case 1: On 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), and corresponds to a 14.50 USD for settlement (settlementAmountValue).
        • The fee paid by the merchant to Alipay for 600 KRW is settled for 0.50 USD.

       

      • Information about the refund:
        • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
        • refundFromAmount: 9000 KRW (transactionAmountValue, and corresponds to 7.25 USD for settlement (settlementAmountValue).
        • The fee returned by Alipay to the merchant for 300 KRW is settled for 0.25 USD.

       

      On December 27, 2018, a CSV file with the file name settlementItems_KaKaoPay_USD_2018122611021040123_000.csv is generated by Alipay, of which 2018122611021040123 is the code for the current settlement cycle.  In this case, the merchant customer ID is 1022188000000000001. The file path is /v1/settlements/1022188000000000001/20181227/settlementItems_KaKaoPay_USD_2018122611021040123_000.csv.


      The settlement details are as follows:

      copy
      settlementBatchId,customerId,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,paymentMethodType,pspName,transactionType,paymentTime,settlementTime,productCode,transactionAmountValue,transactionCurrency,settlementAmountValue,settlementCurrency,quoteCurrencyPair,quotePrice,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
2018122611021040123,1022188000000000001,,,2018122519074101000000000112612,,20190326L648423000404,,KAKAOPAY,KaKaoPay,PAYMENT,2018-12-25T10:00:00+08:30,2018-12-26T10:00:00+08:30,AGREEMENT_PAYMENT,18000,KRW,1450,USD,USD/KRW,1200.0000,-50,USD,
2018122611021040123,1022188000000000001,,,2018122519074102000000000041675,2018122519074101000000000112612,20190326L648423000404,,KAKAOPAY,KaKaoPay,REFUND,2018-12-25T10:00:00+08:30,2018-12-26T10:00:00+08:30,AGREEMENT_PAYMENT,-9000,KRW,-725,USD,USD/KRW,1200.0000,25,USD,0,USD
<END>


      Case 2: On 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 is 18000 KRW (transactionAmountValue), minus 1200 KRW non guaranteed coupon which is 1 USD, corresponding to the settlement of 13.5 USD (settlementAmountValue).
        • The fee paid by the merchant to Alipay for 600KRW is settled for 0.5 USD.

       

      • Information about the refund:
        • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
        • refundFromAmount: 9000 KRW (transactionAmountValue), including 600 KRW non guaranteed coupon which is 0.5 USD, corresponds to 6.75 USD (settlementAmountValue) for settlement.
        • The fee returned by Alipay to the merchant for 300KRW is settled for 0.25USD. 


      On December 27, 2018, a CSV file with the file name settlementItems_KaKaoPay_USD_2018122611021040123_000.csv is generated by Alipay, of which 2018122611021040123 is the code for the current settlement cycle. 


      The settlement details are as follows:

      copy
      settlementBatchId,customerId,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,paymentMethodType,pspName,transactionType,paymentTime,settlementTime,productCode,transactionAmountValue,transactionCurrency,settlementAmountValue,settlementCurrency,quoteCurrencyPair,quotePrice,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency,originalTransactionRequestId
2018122611021040123,1022188000000000001,,,2018122519074101000000000112612,,20190326L648423000404,,KAKAOPAY,KaKaoPay,PAYMENT,2018-12-25T10:00:00+08:30,2018-12-26T10:00:00+08:30,AGREEMENT_PAYMENT,18000,KRW,1350,USD,USD/KRW,1200.0000,-50,USD,-100,USD,
2018122611021040123,1022188000000000001,,,2018122519074102000000000041675,2018122519074101000000000112612,20190326L648423000404,,KAKAOPAY,KaKaoPay,REFUND,2018-12-25T10:00:00+08:30,2018-12-26T10:00:00+08:30,AGREEMENT_PAYMENT,-9000,KRW,-675,USD,USD/KRW,1200.0000,25,USD,50,USD,20190326L648423000404
<END>


      Case 3: Assume that the settlement is T+4 and no transaction exists on December 22, 2018. The settlement date is December 26, 2018.


      On December 26, 2018, an empty CSV file with the file name settlementItems_KaKaoPay_USD_0000000000000000000_000.cs is generated by Alipay.


      The transaction details are as follows: 

      copy
      settlementBatchId,customerId,referenceMerchantId,referenceStoreId,transactionId,originalTransactionId,transactionRequestId,referenceTransactionId,paymentMethodType,pspName,transactionType,paymentTime,settlementTime,productCode,transactionAmountValue,transactionCurrency,settlementAmountValue,settlementCurrency,quoteCurrencyPair,quotePrice,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency,originalTransactionRequestId
<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:

      No.

      Field

      Description

      1

      settlementBatchId

      MANDATORY String (64)

      The unique ID that is assigned by Alipay to identify a settlement cycle, which corresponds to the settlement batch number in the summary file.

      2

      customerId

      MANDATORY String (64)

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

      3

      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.

      4

      referenceStoreId

      OPTIONAL String (64)

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

      5

      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.

      6

      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.

      7

      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.

      8

      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.

      9

      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.

      10

      pspName

      OPTIONAL PSPName

      Name of the payment service provider.

      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.

      11

      transactionType

      MANDATORY TransactionType

      Transaction type. Possible values are:

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

      12

      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.

      13

      settlementTime

      MANDATORY String (64)

      The date and time when the settlement file is generated, in the format of YYYY-MM-DDTHH:MM:SS+hh:mm as defined in ISO 8601.

      14

      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.

      15

      transactionAmountValue

      MANDATORY String (16)

      The transaction amount in the smallest unit of the corresponding currency

      16

      transactionCurrency

      MANDATORY String (3)

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

      17

      settlementAmountValue

      MANDATORY String (16)

      The net settlement amount in the smallest unit of the corresponding currency

      18

      settlementCurrency

      MANDATORY String (3)

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

      19

      quoteCurrencyPair

      OPTIONAL String (16)

      The quotation of the relative value of a currency unit against the unit of another currency in the foreign exchange market. Two currencies are separated with a slash and specified by a 3-letter currency code as defined in ISO 4217.

      20

      quotePrice

      OPTIONAL Decimal (20)

      The exchange rate between the amount in transaction currency and the amount in settlement currency

      21

      feeAmountValue

      MANDATORY String (16)

      The fee amount in the smallest unit of the corresponding currency

      22

      feeCurrency

      MANDATORY String (3)

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

      23

      		nonGuaranteeCouponValue

      OPTIONAL String (16)

      Merchant discount amount, which is not settled to the merchant and is in the smallest unit of the corresponding currency

      24

      nonGuaranteeCouponCurrency

      OPTIONAL String (3)

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

      25

      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 settlement detail file is a text file with UTF-8 code. The file storage path defaults to /v1/settlements/<customerId>/<settlementDate>/, and the file name defaults to settlementItems_<pspName>_<settlementCurrency>_<settlementBatchId>_<seq>.csv. The variables in the file name are described as follows:
        • customerId: the unique ID that is assigned by Alipay to identify a merchant
        • settlementDate: the settlement date
        • pspName: the name of the actual payment service provider. For wallets, the value is the wallet name as defined in PSPName.
        • settlementCurrency: the agreed settlement currency, which is the same as the settlement currency in the file content.
        • settlementBatchId：the settlement batch code corresponds to the settlement batch number in the Summary Files.
        • seq: document serial number. When there are multiple settlement details in the same clearing cycle, each detail file will be increased from 000 to 999.
      • The Settlement Items file is divided into two parts: settlement details and file endings. The file ended with a symbol <END>, which appears in the last line of the file as the file end flag.
      • settlementAmountValue: 

      Settlement amount, which is equal to transactionAmountValue when the Merchant is in the same settlement currency as the transaction currency agreed by Alipay. When the settlement currency agreed between the merchant and Alipay is not the same as the transaction currency, the settlement amount is calculated by the transaction amount according to the agreed exchange rate.

      • feeAmountValue: 

      The total cost amount is the total amount obtained after the cost amount of the exchange is rolled out.