B2B E-Invoice API Document (Certification Mode)

Searching Operations / Search Issue E-invoices

Scenarios

  • Merchant(Business Entity) can use this API to query issued information, including output invoices and input invoices, and Green World will return the results in a parametric manner.
  • This approach helps Merchant to integrate the issuing inquiry mechanism into the Merchant’s website to provide a quick inquiry service.

API URLs:

  • Stage: https://einvoice-stage.ecpay.com.tw/B2BInvoice/GetIssue
  • Production: https://einvoice.ecpay.com.tw/B2BInvoice/GetIssue

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

InvoiceCategory Int
Required

Possible values:

  • 0: Output E-Invoices (Search the invoice issued to the Counterparty from the Merchant).
  • 1: Input E-invoices (Search the invoice of the Counterparty to the Merchant)

InvoiceNumber String(10)
Required

Invoice Number

InvoiceDate String(20)
Required

Invoice Issue date

  • The format is yyyy-mm-dd

RelateNumber String(50)

  • Unique ID of the e-invoice which is defined by the merchant itself.

Example

				
					{
    "MerchantID": "2000132",
    "InvoiceCategory": 0,
    "InvoiceNumber": "SA37758327",
    "InvoiceDate": "2019-08-31",
    "RelateNumber": "2019081602"
}

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.

RtnData String

Example

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "RtnData": "..."
}

Parameters in RtnData

MerchantID String(10)

Merchant ID

InvoiceNumber String(10)

E-Invoice number

InvoiceDate String(20)
The format is yyyy-mm-dd

RelateNumber String(50)

Buyer_Identifier String(8)
Buyer_Name String(60)

Buyer Name

  • Will be output in the form of URL Encode coding
Buyer_Address String(100)

Buyer address

  • Will be output in the form of URL Encode coding
Buyer_TelephoneNumber String(26)

Buyer Telephone

Buyer_EmailAddress String(200)

Buyer Email
Buyer_FacsimileNumber String(26)
Buyer Facsimile
Seller_Identifier String(8)
  • If [InvoiceCategory]=0, then this parameter has no value.

Seller_Name String(60)

Seller Name

  • Will be output in the form of URL Encode coding
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_Address String(100)

Seller address

  • Will be output in the form of URL Encode coding
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_TelephoneNumber String(26)

Seller Telephone
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_EmailAddress String(80)

Seller Email
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_FacsimileNumber String(26)

Seller Facsimile
  • If [InvoiceCategory]=0,then this parameter has no value.
CustomsClearanceMark String(1)

Clearance Method

  • 1:Non-Customs exports
  • 2:Export through Customs
InvoiceType String(1)

Invoice category

  • 07:General tax computation
  • 08:Special tax computation
TaxType Int

Tax Type

  • 1.If [InvoiceType] = 07(General tax computation), then
    please enter 1(Regular Tax)、2(Zero-tax-rate)或3(Tax Free)
  • 2.If[InvoiceType] = 08(Special tax computation), then please enter 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 

TaxRate Number

Tax Rate
  • 1. If [TaxType] = 1(Regular Tax), The parameter is not required (the system will give 0.05)
  • 2. If [TaxType] = 2(Zero-tax-rate), The parameter is not required (the system will give 0)
  • 3. If [TaxType] = 3(Tax Free), The parameter is not required (the system will give 0)
  • 4. If [TaxType] = 4(Special Tax), The parameter is not required (the system will give 0.01~0.99)

SalesAmount Int

Sales Amount
  • 1. Please enter an integer and cannot be $0.
  • 2. Equal to the value that [ItemAmount] summed and rounded to the integer
TaxAmount Int

Tax Amount

TotalAmount Int

Total Amount

  • 1. Please enter an integer and cannot be $0.
  • 2. Equal to the value that [ItemAmount] summed and rounded to the
    integer.
IP String(15)
Issue IP

Create_Date String(20)

E-Invoice issuance time

  • Format is “yyyy-MM-dd HH:mm:ss”.

Issue_Status String(1)

E-Invoice Issuance status

  • 1: E-Invoice Issued
  • 0: E-Invoice invalidated

Invalid_Status String(1)

E-Invoice invalidation status

  • 1: Have been invalidated
  • 0: Not yet invalidated

Upload_Status String(1)

E-Invoice upload status

  • If [InvoiceCategory]=1, then this parameter has no value.
  • 0:Not Uploaded
  • 1:Uploaded
  • 2:Upload Failed

Upload_Date String(20)

E-Invoice upload time

  • Format is “yyyy-MM-dd HH:mm:ss”.
  • If [InvoiceCategory]=1, then this parameter has no value.
ConfirmDate String(20)

Confirm Date

  • 1. The format is yyyy-mm-dd
  • 2. If not set, then this parameter has no value.
ExchangeMode String(1)

Invoice Mode

  • 0:Certification mode
  • 1:Exchange mode
ExchangeStatus String(1)

Invoice Confirm Status

  • If this parameter has no value, it is not set.
  • 0:Not Confirmed
  • 1:Confirmed
BalanceAmount Number

Remaining Allowance Amount

MainRemark String(200)

Invoice Remark

RandomNumber String(4)

Random Number

ItemsArray[Object]

ItemSeq Int

Item Sequence Number

  • 1. Please enter an integer value of 1~999.
  • 2. Sequence number cannot be duplicated

ItemName String(500)

Item Name

ItemCount Number

Merchandise quantity

  • It could be up to 8 integers and 7 decimals after the decimal point.

ItemWord String(6)

Merchandise units

  • 1.The parameter shall be exempted when calculating the check digit.
  • 2.Will be output in the form of URL Encode coding.

ItemPrice Number

Merchandise price

  • Supports up to 8-digits integer and 7-digits decimal
  • Display the price before tax consistently
ItemTax Int

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. 1. This field is only for validating the [TaxAmount]. ECPay will not upload to Ministry of Finance.
  2. 2. If it is special tax, please populate this parameter with 0.

ItemAmount Number

Merchandise total amount

  • 1. Supports up to 12-digits integer and 7-digits 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.

ItemRemark String(120)

Item Remark

Example

				
					{
    "MerchantID": "2000132",
    "InvoiceDate": "2019-08-31",
    "RelateNumber": "2019081602",
    "Buyer_Identifier": "11456006",
    "Buyer_Name": "Eric Shop",
    "Buyer_Address": "200 Taipei",
    "Buyer_TelephoneNumber": "02-12344321",
    "Buyer_EmailAddress": "abc@sunup.net",
    "Buyer_FacsimileNumber": "",
    "CustomsClearanceMark": "",
    "InvoiceType": "07",
    "TaxType": 1,
    "TaxRate": 0.05,
    "SalesAmount": 952,
    "TaxAmount": 48,
    "TotalAmount": 1000,
    "IP": 2130706433,
    "CreateDate": "2019-09-03 13:57:07",   
    "Issue_Status": "1",
    "Invalid_Status": "0",
    "Upload_Status": "1",
    "Upload_Date": "2019-09-03 14:57:07",
    "ConfirmDate": "2019-09-03 15:57:07",
    "ExchangeStatus": "1",
    "ExchangeMode": "0",
    "BalanceAmount": 952,
    "MainRemark": "",
    "RandomNumber": "6686",
    "Items": 
    [
        {
            "ItemSeq": 1,
            "ItemName": "Phone Test",
            "ItemCount": 1,
            "ItemWord": "piece",
            "ItemPrice": 952,
            "ItemAmount": 952,
            "ItemTax": 48,
            "ItemRemark": ""
        }
    ]
}

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

Green World