Issuing Operations / Invalidating and Re-issuing E-invoice

Application Scenarios

The merchant system can use this function to transmit the Invalidate and Reinvoice parameter to Green World, where Green World will temporarily store the corresponding data. Green World will send the data to the merchant system.

Applicable for invoice cancellation and reissuance (invoice number and issuance time must remain unchanged).

Special Notes：

For invoices that need to be voided and reissued, this must be completed by the 13th day of the first month of the next period.
For example: invoices from January-February must be voided and reissued by March 13th; invoices from March-April must be voided and reissued by May 13th.

API URLs:

Stage：https://einvoice-stage.ecpay.com.tw/B2BInvoice/VoidWithReIssue
Prod：https://einvoice.ecpay.com.tw/B2BInvoice/VoidWithReIssue

HTTPS format

Content Type ：application/json
HTTP Method ：POST

Request by Merchant (Json format)

PlatformID String(10)

This parameter is specifically designed for platform vendors collaborating with ECPay. It can only be utilized after applying for and activating the service.
If you are a general vendor, please leave the PlatformID empty.
When using this parameter, the MerchantID must be filled in with the specific store code bound to your PlatformID to prevent operation failures.
Please note that only the MerchantID of a bound sub-merchant can be used to avoid operational failures. For binding operations, please contact your business representative.

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 first and then do AES encryption

MerchantID String(10)

Required

VoidModel Json

Required

E-invoice invalidated data

IssueModel Json

Required

Invoice data

Example

				
					{
   "MerchantID": "2000132",
   "VoidModel": "…",
   "IssueModel": "…"
}

VoidModel (Json) :

InvoiceNo String(10)

Required

E-invoice invalidated data

VoidReason String(20)

Required

Reasons

Example

				
					{
  "InvoiceNo": " MM00000000",
  "VoidReason": "Test"
}

IssueModel (Json) :

RelateNumber String(50)
Required

Unique ID of the e-invoice which is defined by the merchant itself.
Must be a unique value and cannot be duplicated.
Please enter the original invoice number.

Notes：

Only Chinese, English letters, and numbers are allowed.

InvoiceTime String(20)
Required

The format must be either 『yyyy-MM-dd HH:mm:ss』 or 『yyyy/MM/dd HH:mm:ss』.
The invoice issuance time must be earlier than the previous invoice issuance time.

CustomerIdentifier String(8)
Required

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 Issuing and Configuration of trading partners will fail.
Please be sure to provide the Tax ID number (VAT number).

CustomerAddress 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.

Notes：

Do not enter real email addresses in the testing environment to prevent personal data leakage.
The testing environment is for API integration testing only and will respond with success or failure through the API. The batch import feature/API does not support email delivery testing and only verifies format rules.
The regular expression for format validation is:
^((([A–Za–z]|\d|[!#$%&‘*+-/=?^{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([A-Za-z]|\d|[!#\$%&’\*\+\-\/=\?\^_{|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+))|((\x22)((((\x20|\x09)(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))(((\x20|\x09)(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|-|.||~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))).)+(([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|-|.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))).?$

ClearanceMark String(1)

When the tax category [TaxType] is 2 (Zero Tax Rate), this parameter must be set to 1 (Non-Customs Export) or 2 (Customs Export).
When the tax category [TaxType] is not 2 (Zero Tax Rate), please ignore this parameter.

InvType String(2)
Required

07: General tax
08: Special tax

TaxType String(1)
Required

The Type of the tax

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

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

SpecialTaxType String(1)

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.

Items Array[Object]

ItemSeq Number
Required

Please provide an integer value between 1 and 999.
The product order must not be duplicated.

ItemName String(500)
Required

ItemCount Number
Required

Supports up to 8 digits for the integer part and 7 digits for the decimal part.
If this parameter is not provided, the system will default to 0 and directly check whether the difference between item quantity [ItemCount] × item price [ItemPrice] and item total [ItemAmount] is within 1.

ItemWord String(6)

Merchandise units
Goods unit is up to 6 digits.

ItemPrice Number
Required

Supports up to 10 digits for the integer part and 7 digits for the decimal part. Please consistently input the tax-exclusive price.
If this parameter is not provided, the system will default to 0 and directly check whether the difference between item quantity [ItemCount] × item price [ItemPrice] and item total [ItemAmount] is within 1.

ItemAmount Number
Required

Supports up to 12 digits for the integer part and 7 digits for the decimal part.
Define A as [ItemCount] × [ItemPrice]; the difference between the item total and the rounded value of A must not exceed 1.
If this parameter is not provided, the system will default to 0 and directly check whether the difference between item quantity [ItemCount] × item price [ItemPrice] and item total [ItemAmount] is within 1.

ItemTax Number

Please provide an integer with up to 11 digits.
When the tax category [TaxType] is 1 (General Taxable), the system will set the tax rate to 0.05.
When the tax category [TaxType] is 2 (Zero Tax Rate) or 3 (Tax-Exempt), the system will set the tax rate to 0.
When the tax category [TaxType] is 4 (Special Taxable), the tax rate will be determined by the special tax type [SpecialTaxType].
If the item tax [ItemTax] is provided, define B as [ItemAmount] × tax rate; the difference between the item tax and the rounded value of B must not exceed 1.

Notes：

The Ministry of Finance does not provide a format for this parameter; it is offered here for businesses to verify the total business tax amount [TaxAmount] and will not be uploaded.
For special tax invoices, please enter 0 directly.

ItemRemark String(120)

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 Number
Required

Please provide an integer with up to 11 digits.
When the tax category [TaxType] is 1 (General Taxable), the system will set the tax rate to 0.05.
When the tax category [TaxType] is 2 (Zero Tax Rate) or 3 (Tax-Exempt), the system will set the tax rate to 0.
When the tax category [TaxType] is 4 (Special Taxable), the tax rate will be determined by the special tax type [SpecialTaxType].
Define C as the result of multiplying the total sales amount [SalesAmount] by the tax rate, then rounding to the nearest integer. The difference between the total tax amount [TaxAmount] and C must not exceed 2.

Notes：

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 input the item tax [ItemTax] for each product and ensure to adjust the values so that the sum of item tax [ItemTax] differs from the total tax amount [TaxAmount] by less than 2 TWD.

TotalAmount Number
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 [SalesAmountAmount] and the total tax amount [TaxAomunt].

InvoiceRemark String(200)

Example

				
					{
 {
    "RelateNumber": "233e23dhgbdy2dub67287hdweiudwj",
    "InvoiceTime": "2018-10-28 23:12:34",
    "CustomerIdentifier": "",
    "CustomerTelephoneNumber": "",
    "CustomerEmail": "test@ecpay.com.tw",
    "ClearanceMark": "1",
    "InvType": "07",
    "TaxType": "2",
    "ZeroTaxRateReason": "71",
    "SalesAmount": 100,
    "SalesAmount": "100",
    "TaxAmount": "0",
    "TotalAmount": "100",
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "piece",
            "ItemPrice": 50,
            "ItemTaxType": "1",
            "ItemAmount": 50,
            "ItemRemark": "item01_desc"
        },
        {
            "ItemSeq": 2,
            "ItemName": "item02",
            "ItemCount": 1,
            "ItemWord": "piece",
            "ItemPrice": 20,
            "ItemTaxType": "1",
            "ItemAmount": 20,
            "ItemRemark": "item02_desc"
        },
        {
            "ItemSeq": 3,
            "ItemName": "item03",
            "ItemCount": 3,
            "ItemWord": "piece",
            "ItemPrice": 10,
            "ItemTaxType": "1",
            "ItemAmount": 30,
            "ItemRemark": "item03_desc"
        }
    ]
 }
}

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
Respond with relevant data, this is the encrypted JSON format data.
AES Encryption Description

Example

				
					{
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "..."
}

Data參數說明(Json格式) : 請先將Data進行AES解密後再做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)

InvoiceNo String(10)

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)

Data參數範例

				
					{
   "RtnCode": 1,
   "RtnMsg": "Success",
   "InvoiceNo": "20181028000000001"
   "RandomNumber": "6866"
}

Green World