Settlement Summary
The Settlement Summary report is used to provide the merchant with a summary of the clearing data information. A Settlement Summary report is provided for each clearing cycle and contains the total number of transactions during the period, the amount of liquidation after rolling, and other related information. When no transaction occurs during a clearing cycle, the summary file is still provided, but the total amount is 0.
Report path and name
The Settlement Summary report is a text file with UTF-8 encoding. The report storage path defaults to /v1/settlements/<customerId>/<settlementDate>/ plus the file name. The file name differs for each settlement mode:
Settlement by multiple payment methods:
The report name is settlementSummary_<settlementCurrency>_<settlementBatchId>_<seq>.csv.
Settlement by single payment method:
The report name is different for Alipay+ MPPs and other payment methods.
- For Alipay+ MPPs:
- When Alipay+ MPPs are settled together:
settlementSummary_CONNECTWALLET_<settlementCurrency>_<settlementBatchId>_<seq>.csv - When Alipay+ MPPs are settled individually:
settlementSummary_<pspName>_<settlementCurrency>_<settlementBatchId>_<seq>.csv
- For other payment methods:
settlementSummary_<paymentMethodType>_<settlementCurrency>_<settlementBatchId>_<seq>.csv
Details about the variables in the report name:
- 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 reports.
- seq: the 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.
Report fields
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. The settlement summary 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 |
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. |
processingFeeAmountValue | OPTIONAL String (16) The amount of the processing fee that is charged for the payment processing services Alipay provided for each transaction. The value of processingFeeAmountValue is in the smallest unit of the corresponding currency. |
processingFeeCurrency | OPTIONAL String (3) The currency of processingFeeAmountValue. The value of processingFeeCurrency is specified by a 3-letter currency code as defined in ISO 4217. |
Report samples
Settlement for single payment method
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, corresponding to the settlement of 14.50 USD (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.
- 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:
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>Sample 2
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 for 600 KRW 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:
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>Sample 3
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:
settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
<END>Settlement for multiple payment methods
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, corresponding to the settlement of 14.50 USD (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.
- 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:
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>Sample 2
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 for 600 KRW 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:
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>Sample 3
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:
settlementBatchId,customerId,summaryType,settlementTime,count,settlementAmountValue,settlementCurrency,feeAmountValue,feeCurrency,nonGuaranteeCouponValue,nonGuaranteeCouponCurrency
<END>