Settlement Items
The Settlement Items file contains settlement details in a settlement cycle. The settlement details are provided in a document, and generated with a summary file of the settlement cycle. Alipay uploads the file to a specified directory in SFTP for merchants to download and use.
Samples
Case 1: Settlement for single wallet
a. 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>b. 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:
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>c. 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:
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>Case 2: Settlement for multiple wallets
a. 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 26, 2018, a CSV file with the file name settlementItems_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/20181226/settlementItems_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>b. 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 26, 2018, a CSV file with the file name settlementItems_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
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
<END>c. No transaction exists on December 25, 2018. On December 26, 2018, a CSV file with the file name settlementItems_USD_2018122611021040123_000.csv is generated by Alipay, of which 2018122611021040123 is the code of the current split period.
The transaction 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
<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. |
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 are:
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. |
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. |
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 differs for each settlement mode:
- Settlement for single wallet:
settlementItems_<pspName>_<settlementCurrency>_<settlementBatchId>_<seq>.csv. - Settlement for multiple wallets:
settlementItems_<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 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: 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.