Scenarios
Seller to issue the allowance.
- According to the Ministry of Finance’s Electronic Invoice Specification MIG Version 4.1, B2B electronic allowance operations can only be initiated by the original invoice issuer (i.e., the Merchant).
- After the invoice message is issued by the Merchant (Business Entity), if a return of sales, exchange, or price allowance occurs, and an agreement is reached with the Counterparty (Business Entity) to the transaction, the Merchant initiates the allowance process and sends the allowance invoice parameters to Green World.
- Green World uploads the allowance invoice to The E-Invoice Platform of Ministry of Finance, and notifies the Counterparty according to the configuration in the Send E-invoices Status Notices.
Special Notes :
- To comply with the Ministry of Finance’s latest Electronic Invoice MIG 4.1 regulations, B2B allowance invoices can only be initiated by the Merchant.
- After the allowance invoice is uploaded, it still requires confirmation by the Counterparty (Business Entity) to complete the exchange and make the allowance valid.
- According to the Ministry of Finance’s regulations, the Counterparty (Business Entity) must complete confirmation to avoid disputes.
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
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(200)
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
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
- Please enter an integer value of 1~999.
- The order of the allowance items must be the same as the order of
the items in the original invoice.
ItemName String(500)
Required
The allowanced item name [ItemName] must be the same as the corresponding item name in the original invoice number order.
ItemCount Number
Required
- Supports up to 8-digit integer and 7-digit decimal.
- The quantity of allowanced products [ItemCount] cannot exceed the quantity of the original invoiced item.
ItemPrice Number
Required
- Supports up to 10-digit integer and 7-digit decimal.
- The allowanced price [ItemPrice] cannot exceed the price of the original invoiced item.
Tax Int
- The item tax amount for the discount is defined as: [Total discounted item amount (ItemAmount) × tax rate from the invoice issuance API (TaxRate)] = B.
- The difference between the discounted item tax amount [Tax] and the value of B rounded to the nearest integer must not exceed 1.
It must be an integer with up to 11 digits. - For special tax invoices, please enter 0 directly.
ItemAmount Number
Required
- Supports up to 12-digit integer and 7-digit decimal.
- 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)
RpHeader
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"
}