Scenarios
- After the Merchant sends the issuing parameters to Green World Technology Value-Added Center(hereinafter referred to as Green World), the relevant information will be temporarily stored by Green World.
- Green World will issue the invoice on the next day and upload it to The E-Invoice Platform of Ministry of Finance and notify the Counterparty (Business Entity) that the E-invoice has been issued according to the Send E-invoices Status Notices API setting.
Special notes : Wait for the transaction counterpart (Business Entity) to confirm, at which time the invoice status is issued successfully and is a valid certificate, but the exchange has not been completed. The invoice cannot be allowanced or canceled. API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2BInvoice/Issue
- Production: https://einvoice.ecpay.com.tw/B2BInvoice/Issue
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
RelateNumber String(20)
Required
- Unique ID of the e-invoice which is defined by the merchant itself.
- Issue Time
- The format is yyyy-mm-dd hh:mm:ss
Special notes :
- 1. If the parameter has a value, only the date within the last 6 days will be accepted. It is recommended to leave this field blank and ECPay will automatically populate it with the issuing date.
- 2. Please note that the invoice should be issued in the order of time and invoice number.
CustomerIdentifier String(8)
- Tax ID number (VAT number) of customer’s company
- The tax number or VAT ID of the person to whom the goods or services were supplied. In Taiwan, it should be an 8-digit number.
- In order to provide better issuing services,
the Ministry of Finance is expected to update the logic of CustomerIdentifier field from divisible by “10” to divisible by “5” on January 1, 2023,
to facilitate the correct issuing with the Tax ID number (VAT number).
The adjustment is explained as follows.
According to the announcement of the Financial Information Center of the Ministry of Finance, the check logic of the Tax ID number (VAT number) is changed from “divisible by 10” to “divisible by 5”.
For more details, please refer to the Ministry of Finance’s Financial Information Center Tax ID number of customer’s company check code logic correction instructions
If the above check logic is not met, the function of Isussing and Configuration of trading partners will fail.
Please be sure to provide the Tax ID number (VAT number).
CustomerAddr String(100)
CustomerTelephoneNumber String(26)
CustomerEmail String(200)
- The email of the customer you are invoicing.
- (1). This is optional if CustomerPhone is sent (i.e. either CustomerPhone or CustomerEmail is required.)
- (2). If it is sent, only valid email format is acceptable (i.e. an email prefix and an email domain, both in acceptable formats. The prefix appears to the left of the @ symbol. The domain appears to the right of the @ symbol.)
- (3). Only one email address is acceptable, while more than one is not allowed.
Special notes :
- When testing ECPay’s API on Stage (API URL: https://einvoice-stage.ecpay.com.tw/B2BInvoice/Issue), please do not place your real email address in order to avoid personal data breach.
- 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 e-invoice is created, the Stage will not support sending email notification feature, but the Production will.
ClearanceMark String(1)
If [TaxType] = 2 (Zero-tax-rate), possible values:
- 1: Export not through customs.
- 2: Export through the customs.
InvType String(2)
Required
- 07: General tax
- 08: Special tax
TaxType String(1)
Required
- When [InvTyp] is 07 (general tax), please enter 1, 2, 3 in this field.
- 1: Regular Tax
- 2: Zero-tax-rate
- 3: Tax Free
- If [InvType] is 08 (special tax), then please enter 3 or 4 in this field.
- 4: Special tax
Tax Rate
- 1. If [TaxType] = 1 (Regular Tax), this parameter is not required (ECPay will automatically set the rate as 5%, which is 0.05.)
- 2. If [TaxType] = 2 (Zero-tax-rate), this parameter is not required (ECPay will automatically set the rate as 0.)
- 3. If [TaxType] = 3 (Tax Free), this parameter is not required(ECPay will automatically set the rate as 0.)
- 4. If [TaxType] = 4 (Special Tax), this parameter is not required (ECPay will automatically set the rate range as 0.01-0.99.)
ZeroTaxRateReason String(2)
Starting from January 1, 2026, when the tax category [TaxType] is 2 (zero-rated), this field is mandatory or must be configured in the merchant’s backend for the system to retrieve the data correctly. Otherwise, the invoice issuance will fail. The valid values are as follows:
71: (Item 1) Exported goods
72: (Item 2) Export-related services or services provided domestically but used abroad
73: (Item 3) Sales by duty-free shops established in accordance with the law to transit or outbound passengers
74: (Item 4) Sales of goods or services to enterprises in bonded zones for operational use
75: (Item 5) International transportation services. However, for foreign transportation enterprises operating international transport services within the Republic of China, such services are limited to those granted reciprocal treatment or tax exemption by their home countries
76: (Item 6) Vessels, aircraft, and deep-sea fishing boats used for international transportation
77: (Item 7) Sales of goods or repair services for vessels, aircraft, and deep-sea fishing boats used for international transportation
78: (Item 8) Sales by bonded zone enterprises to taxable zone enterprises where the goods are directly exported without entering the taxable zone
79: (Item 9) Sales by bonded zone enterprises to taxable zone enterprises where the goods are stored in Free Trade Zone enterprises or customs-controlled bonded warehouses/logistics centers for export purposes
Special Tax Type
- If [TaxType] = 3 (tax-free), this parameter will be required and the value should be “8”.
- If [TaxType] = 4 (special tax), this parameter will be required and the value could be 1-8, following detail the tax rate and definition of each value:
- 1: The tax rate is 25%, indicating the business tax rate of saloons and tea rooms, coffee shops and bars offering companionship services.
- 2: The tax rate is 15%, indicating the tax rate of night clubs or restaurants providing entertaining show programs.
- 3: The tax rate is 2%, indicating the business tax rate of revenues connected exclusively from their core business, such as banking, insurance, investment trusts, securities, futures, commercial paper and pawnshops (not including the banking and insurance business of the banking and insurance industries.)
- 4: The tax rate is 1%, indicating the business tax rate of the revenues from premium income and reinsurance premium income.
- 5: The tax rate is 5%, indicating the business tax rate of revenues NOT connected exclusively from their core business, such as banking, insurance, investment trusts, securities, futures, commercial paper and pawnshops.
- 6: The tax rate is 5%, indicating business tax rate from the revenues of the banking and insurance business of the banking and insurance industries (applicable for the sales income AFTER July, 2014.)
- 7: The tax rate is 5%, indicating business tax rate from the revenues of the banking and insurance business of the banking and insurance industries (applicable for the sales income BEFORE July, 2014.)
- 8: indicating blank invoice which are not used, the tax free (if [TaxType]=3) or not applicable to the special tax.
SalesAmount Int
Required
- Please provide an integer with up to 12 digits, and it must not be zero.
- It must equal the sum of the product totals [ItemAmount], rounded to the nearest integer.
TaxAmount Int
Required
- Please provide an integer with up to 11 digits.
- Define C as the result of multiplying the total sales amount [SalesAmount] by the tax rate [TaxRate], then rounding to the nearest integer. The difference between the total tax amount [TaxAmount] and C must not exceed 2.
- For special tax invoices, please enter 0 directly.
- When receiving the error message “The discrepancy between the total item tax and the business tax exceeds 2 TWD”, please fill in the item tax [ItemTax] for each product, and ensure to adjust the values so that the total item tax [ItemTax] differs from the total tax amount [TaxAmount] by less than 2 TWD.
TotalAmount Int
Required
- Please provide an integer with up to 12 digits, and it must not be zero.
- It must equal the sum of the total sales amount [SalesAmount] and the total tax amount [TaxAmount].
InvoiceRemark String(200)
Items Array
ItemSeq Int
Item Sequence Number
- 1. Please enter an integer value of 1~999.
- 2. Sequence number cannot be duplicated.
ItemName String(500)
Required
Item Name
ItemCount Number
Required
- Merchandise quantity
- It could be up to 8 integers and 7 decimals after the decimal point.
ItemWord String(6)
Merchandise units
- Goods unit is up to 6 digits.
ItemPrice Number
Required
Merchandise price
- Supports up to 8-digits integer and 7-digit decimal
- Please enter the price before tax
Tax of individual item/product
- 1. Only integer acceptable.
- 2. If this parameter has value, the difference between [ItemTax] and B (B = [ItemAmount]*[TaxRate] after being rounded) should not be larger than 1.
Special notes :
- 1. This field is only for validating the [TaxAmount]. ECPay will not upload to Ministry of Finance.
- 2. If it is special tax, please populate this parameter with 0.
ItemAmount Number
Required
Special notes :
- It could be up to 12 integers and 7 decimals after the decimal point.
- If set [ItemCount]*[ItemPrice] as A, then the difference between [ItemAmount] and the value of A after rounding must not be greater than 1.
ItemRemark String(120)
Example
{
"MerchantID": "2000132",
"RelateNumber": "20190922000000003",
"InvoiceTime": "2019/09/22 00:00:00",
"CustomerIdentifier": "23165448",
"CustomerEmail": "",
"ClearanceMark": "1",
"InvType": "07",
"TaxType": 1,
"TaxRate": 0.05,
"SalesAmount": 100,
"TaxAmount": 5,
"TotalAmount": 105,
"InvoiceRemark": "Invoices Remark",
"Items": [
{
"ItemSeq": 1,
"ItemName": "item01",
"ItemCount": 1,
"ItemWord": "piece",
"ItemPrice": 50,
"ItemAmount": 50,
"ItemTax": 2,
"ItemRemark": "item01_desc"
},
{
"ItemSeq": 2,
"ItemName": "item02",
"ItemCount": 1,
"ItemWord": "piece",
"ItemPrice": 20,
"ItemAmount": 20,
"ItemTax": 1,
"ItemRemark": "item02_desc"
},
{
"ItemSeq": 3,
"ItemName": "item03",
"ItemCount": 3,
"ItemWord": "piece",
"ItemPrice": 10,
"ItemAmount": 30,
"ItemTax": 2,
"ItemRemark": "item03_desc"
}
]
}
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.
- Number of e-invoice
- If the issuance is successfully completed then a set of E-Invoice number will be sent in response; If the issuance failed then a blank value will be sent in response.
RandomNumber String(4)
Example
{
"RtnCode": 1,
"RtnMsg": "Success",
"InvoiceNumber": "VG11000002",
"RandomNumber": "6686"
}