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

      Settlement Summary

      The Settlement Summary file is used to provide the merchant with a summary of the clearing data information. A Settlement Summary file is provided for each clearing cycle. 


      The file contains the total number of transactions during the period, the amount of liquidation after rolling, and other related information. Each Summary file contains the transaction details and expense details during the cycle.


      #Samples

      Case 1: Settlement for single wallet

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


      • Information about the refund:
        • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
        • refundAmount: 9,000 KRW (transactionAmountValue) for refund, corresponding to the settlement of 7.25 USD (transactionAmountValue).
        • The fee returned by Alipay to the merchant for 300 KRW is settled for 0.25 USD.


      On December 27, 2018, the CSV file of the file named settlementSummary_KaKaoPay_USD_2018122611021040123_000.csv will be generated by Alipay, of which 2018122611021040123 is the code of the current clearing period. In this case, the merchant customer id is 1022188000000000001. The file path is /v1/settlements/1022188000000000001/20181226/settlementItems_KaKaoPay_USD_2018122611021040123_000.csv.


      The transaction details are as follows:

      copy
      settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
      2018122611021040123,1022188000000000001,TOTAL,2018-12-26T10:00:00+08:30,2,725,USD,-25,USD,0,USD,
      2018122611021040123,1022188000000000001,PAYMENT,2018-12-26T10:00:00+08:30,1,1450,USD,-50,USD,0,USD,
      2018122611021040123,1022188000000000001,REFUND,2018-12-26T10:00:00+08:30,1,-725,USD,25,USD,0,USD
      <END>


      b. 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 a payment:
        • paymentId: 2018122519074101000000000112612, which is also the value of transactionId.
        • paymentAmount: 18000 KRW (transactionAmountValue) for payment, minus 1200 KRW non guaranteed coupon which is 1.00 USD, corresponding to the settlement of 13.50 USD (settlementAmountValue).
        • The fee paid by the merchant to Alipay is 600 KRW, which is settled for 0.50 USD.


      • Information about a refund:
        • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
        • refundAmount: 9,000 KRW (transactionAmountValue) refund, including 600 KRW non guaranteed coupon which is 0.50 USD, corresponding to the settlement of 6.75 USD (transactionAmountValue).
        • The fee returned by Alipay to the merchant for 300 KRW is settled for 0.25 USD.


      On December 27, 2018, the CSV file of the file name settlementSummary_KaKaoPay_USD_2018122611021040123_000.csv will be generated by Alipay, of which 2018122611021040123 is the code of the current clearing period.


      The transaction details are as follows:

      copy
      settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency,extendInfo
      2018122611021040123,1022188000000000001,TOTAL,2018-12-26T10:00:00+08:30,2,675,USD,-25,USD,-50,USD,
      2018122611021040123,1022188000000000001,PAYMENT,2018-12-26T10:00:00+08:30,1,1350,USD,-50,USD,-100,USD,
      2018122611021040123,1022188000000000001,REFUND,2018-12-26T10:00:00+08:30,1,-675,USD,25,USD,50,USD
      <END>


      c. No transaction exists on December 25, 2018. On December 26, 2018, Alipay generates a CSV file with the file name settlementSummary_KaKaoPay_USD_0000000000000000000_000.csv.


      The transaction details are as follows: 

      copy
      settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
      <END>


      Case 2: Settlement for multiple wallets

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


      • Information about the refund:
        • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
        • refundAmount: 9,000 KRW (transactionAmountValue) for refund, corresponding to the settlement of 7.25 USD (transactionAmountValue).
        • The fee returned by Alipay to the merchant for 300 KRW is settled for 0.25 USD.


      On December 26, 2018, the CSV file of the file named settlementSummary_USD_2018122611021040123_000.csv will be generated by Alipay, of which 2018122611021040123 is the code of the current clearing period. In this case, the merchant customer id is 1022188000000000001. The file path is /v1/settlements/1022188000000000001/20181226/settlementSummary_USD_2018122611021040123_000.csv.


      The transaction details are as follows:

      copy
      settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
      2018122611021040123,1022188000000000001,TOTAL,2018-12-26T10:00:00+08:30,2,725,USD,-25,USD,0,USD,
      2018122611021040123,1022188000000000001,PAYMENT,2018-12-26T10:00:00+08:30,1,1450,USD,-50,USD,0,USD,
      2018122611021040123,1022188000000000001,REFUND,2018-12-26T10:00:00+08:30,1,-725,USD,25,USD,0,USD
      <END>


      b. 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 a payment:
        • paymentId: 2018122519074101000000000112612, which is also the value of transactionId.
        • paymentAmount: 18000 KRW (transactionAmountValue) for payment, minus 1200 KRW non guaranteed coupon which is 1.00 USD, corresponding to the settlement of 13.50 USD (settlementAmountValue).
        • The fee paid by the merchant to Alipay is 600 KRW, which is settled for 0.50 USD.


      • Information about a refund:
        • refundId: 2018122519074102000000000041675, which is also the value of transactionId.
        • refundAmount: 9,000 KRW (transactionAmountValue) refund, including 600 KRW non guaranteed coupon which is 0.50 USD, corresponding to the settlement of 6.75 USD (transactionAmountValue).
        • The fee returned by Alipay to the merchant for 300 KRW is settled for 0.25USD.


      On December 26, 2018, the CSV file of the file name settlementSummary_USD_2018122611021040123_000.csv will be generated by Alipay, of which 2018122611021040123 is the code of the current clearing period.


      The transaction details are as follows:

      copy
      settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency,extendInfo
      2018122611021040123,1022188000000000001,TOTAL,2018-12-26T10:00:00+08:30,2,675,USD,-25,USD,-50,USD,
      2018122611021040123,1022188000000000001,PAYMENT,2018-12-26T10:00:00+08:30,1,1350,USD,-50,USD,-100,USD,
      2018122611021040123,1022188000000000001,REFUND,2018-12-26T10:00:00+08:30,1,-675,USD,25,USD,50,USD
      <END>


      c. No transaction exists on December 25, 2018. On December 26, 2018, Alipay generates a CSV file with the file name settlementSummary_USD_2018122611021040123_000.csv, of which 2018122611021040123 is the code of the current clearing period.


      The transaction details are as follows:

      copy
      settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
      <END>


      #Structure

      #File head

      N/A

      #File body

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

      Field

      Description

      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.

      customerId

      MANDATORY String (64)

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

      summaryType

      OPTIONAL String (16)

      Type of the summary row. Possible values include PAYMENT, REFUND, CANCEL, or TOTAL.

      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.

      count

      MANDATORY Integer

      The number of records, indicating the number of transactions that exist in total.

      settlementAmountValue

      MANDATORY String (16)

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

      settlementCurrency

      MANDATORY String (3)

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

      feeAmountValue

      MANDATORY String (16)

      The fee amount in the smallest unit of the corresponding currency.

      feeCurrency

      MANDATORY String (3)

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

      nonGuaranteeCouponValue

      OPTIONAL String (16)

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

      nonGuaranteeCouponCurrency

      OPTIONAL String (3)

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


      #More information

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

      • The Settlement Summary File is a text file with UTF-8 encoding. The file storage path defaults to /v1/settlements/<customerId>/<settlementDate>/, and the file name differs for each settlement mode:
        • Settlement for single wallet: settlementSummary_<pspName>_<settlementCurrency>_<settlementBatchId>_<seq>.csv
        • Settlement for multiple wallets: settlementSummary_<settlementCurrency>_<settlementBatchId>_<seq>.csv

      The parameters in the file path and name are as follows:

        • customerId: the identity that Alipay assigns to the merchant.
        • settlementDate: the settlement date.
        • pspName: the name of the actual Alipay+ Mobile Payment Partner. For wallets, the value is the wallet name as defined in PSPName.
        • settlementCurrency: the agreed settlement currency, which is the same as the expense 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 expense details in the same clearing cycle, each detail file will be increased from 000 as needed, up to 999.
      • The Settlement Summary document is divided into two parts: Settlement Summary and file end symbol. The file end symbol <END> appears in the last line of the file as the file end flag.
      • When no transaction occurs during a clearing cycle, the summary file is still provided, but the total amount is 0.
      • transactionCurrency:This field can be empty. This field is empty when there is no transaction under the clearing cycle or there are multiple transaction currencies under the clearing cycle.
      • transactionAmountValueSimilar to TransactionCurrency, this field can be empty. This field is empty when there is no transaction under the clearing cycle or there are multiple transaction currencies under the clearing cycle.