Scenarios
- The return of sales, exchange or allowance of goods after the invoice message is issued by the Merchant(Business Entity).
- Upon agreement with the Counterparty to the transaction, Merchant sends the allowanced invoice parameters to Green World and Green World stores the relevant data.
- Green World uploads the allowance invoice the next day to The E-Invoice Platform of Ministry of Finance, which is set up according to the Send E-invoices Status Notices API to notify the transaction Counterparty (Business Entity) .
HTTPS format
- Content Type ：application/json
- HTTP Method ：POST
Request by Merchant (Json format)
PlatformID String(10)
- Platform merchant ID
- This parameter is provided by ECPAY to the platform vendor for project cooperation, please bring in the MerchantID bound with the platform vendor.
- Please leave empty for general vendor.
- When the platform vendor uses the MerchantID field, it can only bring in the MerchantID that has been bound as a sub-store, otherwise it will cause a failure.
MerchantID String(10)
Required
RqHeader
Object
Required
Request header
Timestamp Number
Required
- Please convert the transmission time to a timestamp (GMT+8).
- ECPay will use this parameter to convert the current time to Unix TimeStamp to verify the time interval of this connection.
Special Notes：
- If ECPay receives the API call is more 10 minutes late than the timestamp sent by merchants, this request will be failed. Reference information is as follows：http://www.epochconverter.com/。
- Merchants are suggested to frequently synchronize the time zone of server to another server of the nearest time zone.
Data String
Required
- Message payload
- This is the encrypted data in JSON format.
AES Encryption Description
Example
{
"MerchantID": "2000132",
"RqHeader": {
"Timestamp": 1525168923
},
"Data": "..."
}
Message payload of Data(Json format) : please urlencode the JSON string firstly and then do AES encryption
MerchantID String(10)
Required
AllowanceDate String(20)
Allownace Date
- The format is yyyy-mm-dd hh:mm:ss
- If the parameter has a value, only the date within the last 6 days will be accepted; if there is no value, the current date will be used to issue it.
CustomerEmail String(80)
Buyer Email
- 1. Only the valid format is accepted (i.e. local-part@domain).
- 2. Please use semicolon to separate more than one email address. If no value, ECPay will automatically populate this parameter with the data set by Transaction object maintenance API.
Special Notes:
- 1. When testing ECPay’s API on Stage (API URL: https://einvoice-stage.ecpay.com.tw/B2BInvoice/Allowance), please do not place your real email address in order to avoid personal data breach.
- 2. When testing ECPay’s API on Stage, ECPay’s API will respond success or failure only and the API will validate if the email address is valid or not. Once the allowance e-invoice is created, the Stage will not support sending email notification feature, but the Production will.
CustomerAddress String(100)
TaxAmount Int
Tax Amount
- 1. Please enter an integer.
- 2. If set [TotalAmount]* Tax rate for issued API [TaxRate] as C, then the difference between [TaxAmount] and the value of C after rounding must not be greater than 2.
TotalAmount Int
Total Allowance Amount(Untaxed)
- 1. Please enter an integer and cannot be 0.
- 2. [TotalAmount] equal to the allowanced [ItemAmount] of each invoice and rounded to the integer.
Details Array[Object]
OriginalInvoiceNumber String(10)
Required
Original Invoice Number
OriginalInvoiceDate String(20)
Required
Original Invoice Date
- The format is yyyy-mm-dd
OriginalSequenceNumber Int
Required
Original Sequence Number
- 1. Please enter an integer value of 1~999.
- 2. The order of the allowance items must be the same as the order of
the items in the original invoice.
ItemName String(256)
Required
The allowanced item name [ItemName] must be the same as the corresponding item name in the original invoice number order.
ItemCount Number
Required
- 1. Supports up to 8-digit integer and 2-digit decimal.
- 2. The quantity of allowanced products [ItemCount] cannot exceed the quantity of the original invoiced item.
ItemPrice Number
Required
- 1. Supports up to 8-digit integer and 7-digit decimal.
- 2. The allowanced price [ItemPrice] cannot exceed the price of the original invoiced item.
Tax Int
- 1. Must be an integer.
- 2. If [Tax] has the value and set [ItemAmount]* Tax rate for issued API [TaxRate] as B, then the difference between [Tax] and the value of B after rounding must not be greater than 1
ItemAmount Number
Required
- 1. Supports up to 12-digit integer and 7-digit decimal.
- 2. If set [ItemCount]*[ItemPrice] as A, then the difference between [ItemAmount] and the value of A after rounding must not be greater than 1.
Example
{
"MerchantID": "2000132",
"AllowanceDate": "2019-09-24 00:00:00",
"CustomerEmail": "abc1234@gmail.com",
"TaxAmount": 1,
"TotalAmount": 24,
"Details": [
{
"OriginalInvoiceNumber": "VG11000003",
"OriginalInvoiceDate": "2019-09-24",
"OriginalSequenceNumber": 1,
"ItemName": "Small Bear",
"ItemCount": 2,
"ItemPrice": 12,
"ItemAmount": 24,
"Tax": 1
}
]
}
Response format
- Content Type ：application/json
- HTTP Method ：POST
Response by ECPay (Json format)
PlatformID String(10)
MerchantID String(10)
Required
RpHeader
Object
Response header
Timestamp Number
Unix timestamp(GMT+8)
TransCode Int
- Response code to indicate whether the payload is successfully accepted
- Possible values:
1: Payload (i.e. MerchantID, RqHeader, and Data) is successfully accepted by ECPay.
Others: failed.
TransMsg String(200)
Response message to indicate whether the payload is successfully accepted
Data String
- Message payload
- Responde relevant data, this is the encrypted JSON format data。
AES Encryption Description
Example
{
"MerchantID": "2000132",
"RpHeader": {
"Timestamp": 1525169058
},
"TransCode": 1,
"TransMsg": "",
"Data": "..."
}
Message payload of Data(Json format) : please do AES decryption to the Data firstly and then do urldecode.
RtnCode Int
- Return codes to indicate whether the API is successfully executed or not.
- Possible values:
- 1: API is successfully executed.
- Others: failed.
RtnMsg String(200)
Return messages to indicate whether the API is successfully executed or not.
AllowanceNo String(16)
ECPay Allowance Number
- If the allowance is issued successfully, ECPay will assign and return an allowance number; if fails, a null value will be returned.
AllowanceNumber String(16)
Merchant Allowance Number
- The allowance number provided by the merchant.
Example
{
"RtnCode": 1,
"RtnMsg": "Success",
"AllowanceNo": "1909241702402030",
"AllowanceNumber": "1909241702402030"
}