Settlement Items
The settlement Items report is used by Alipay to provide merchants with settlement details in a settlement cycle.
Report path and name
The settlement details report is a text file with UTF-8 code and is uploaded to a specified directory in SFTP for merchants to download and use. The file storage path defaults to /v1/settlements/<customerId>/<settlementDate>/ plus report name. The report name differs for each settlement mode:
Settlement by multiple payment methods:
The report name is settlementItems_<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:
settlementItems_CONNECTWALLET_<settlementCurrency>_<settlementBatchId>_<seq>.csv - When Alipay+ MPPs are settled individually:
settlementItems_<pspName>_<settlementCurrency>_<settlementBatchId>_<seq>.csv
- For other payment methods:
settlementItems_<paymentMethodType>_<settlementCurrency>_<settlementBatchId>_<seq>.csv
Details about the variables in the report name:
- customerId: the unique ID that is assigned by Alipay to identify a 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 settlement currency in the file content.
- settlementBatchId: the settlement batch code corresponds to the settlement batch number in the Summary Files.
- seq: the document serial number. When there are multiple settlement details in the same clearing cycle, each detail file will be increased from 000 to 999.
Report fields
The Settlement Items report is divided into two parts: settlement details and file endings. The report ends with a symbol of <END>, which appears in the last line of the report as the file end flag. The settlement 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. |
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:
|
originalTransactionId | OPTIONAL String (64) An identifier for the original transaction.
|
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. |
paymentMethodType | MANDATORY String (32) Payment method type of the payment that is processed. For auto debit payments and cashier payments, possible values include:
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 PSPName Name of Alipay+ Mobile Payment Partner. 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:
|
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. |
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. |
productCode | MANDATORY ProductCodeType The type of the payment product that is contracted between Alipay and the merchant. Possible values are:
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. |
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. |
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. |
quotePrice | OPTIONAL Decimal (20) The exchange rate between the amount in the transaction currency and the amount in the settlement currency. |
feeAmountValue | MANDATORY String (16) The fee amount in the smallest unit of the corresponding currency. Note: The total cost amount is the total amount obtained after the cost amount of the exchange is rolled out. |
feeCurrency | MANDATORY String (3) The currency of feeAmountValue, specified by a 3-letter currency code as defined in ISO 4217. |
| nonGuaranteeCouponValue | OPTIONAL String (16) 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. |
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. |
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 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:
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>Sample 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.00 USD, corresponding to the settlement of 13.50 USD (settlementAmountValue).
- The fee paid by the merchant to Alipay for 600KRW is settled for 0.50 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.50 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:
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>Sample 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 of settlementItems_KaKaoPay_USD_0000000000000000000_000.cs is generated by Alipay.
The settlement details are as follows:
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>