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.
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/VoidWithReIssue
- Production: https://einvoice.ecpay.com.tw/B2CInvoice/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 more than 10 minutes after the timestamp sent by merchants, this request will fail. Reference information is as follows：http://www.epochconverter.com/。
- Merchants are advised to frequently synchronize their server’s time to the nearest time zone server.
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
VoidModel JSON
Required
E-invoice invalidated data
IssueModel JSON
Required
Invoice data
Example
{
"VoidModel": "…",
"IssueModel": "…"
}
VoidModel (JSON) :
MerchantID String(10)
InvoiceNo String(10)
Required
E-invoice invalidated data
VoidReason String(20)
Required
Reasons
Example
{
"InvoiceNo": " MM00000000",
"VoidReason": "Test"
}
IssueModel (JSON) :
MerchantID String(10)
RelateNumber String(30)
Required
Unique ID of the e-invoice which is defined by the merchant itself.
InvoiceDate String(20)
Required
- Time of e-invoice created
- The format: yyyy-MM-dd HH:mm:ss
CustomerID String(20)
- Customer ID
- This parameter enables merchants who have a member system to input the ID of individual consumer (customer).
Special notes : Only English letters, numbers, and underscore are acceptable. For example, abc_123
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 Issuing and Configuration of trading partners will fail.
Please be sure to provide the Tax ID number (VAT number).
CustomerName String(60)
- The name of the customer you are invoicing.
- This will be required if Print=1.
(1). If it is required, about the format, only numbers and Chinese or English characters are acceptable.
(2). If it is required, CustomerIdentifier should be required as well. In this case, the CustomerIdentifier should be populated with the name of the customer’s company.
CustomerAddr String(100)
- The address of the customer to receive the e-invoice
- This will be required if Print=1.
CustomerPhone String(20)
- The phone number of the customer you are invoicing.
- (1). This is optional if CustomerEmail is sent (i.e. either CustomerPhone or CustomerEmail is required.)
(2). If it is sent, only numbers are acceptable.
CustomerEmail String(80)
- 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 :
1. When testing ECPay’s API on Stage (API URL: https://einvoice-stage.ecpay.com.tw/B2CInvoice/Issue), 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 e-invoice is created, the Stage will not support sending email notification feature, but the Production will.
ClearanceMark String(1)
- A mark to indicate whether the goods is through the customs or not.
- This is required if the TaxType is provided as 2 (no tax).
Possible value:
1: If the goods is NOT via the customs.
2: Via the customs.
Print String(1)
Required
- A mark to indicate whether this e-invoice is to be generated as PDF or not.
- 0: Not to print
1: To print
Special notes :
- If the donation note [Donation ]= “1” (Donation), please fill in 0.
- If the unified Business No. [CustomerIdentifier] has a value :
2.a If the carrier type [CarrierType] be empty, please fill in 1.
2.b If the carrier type [CarrierType]= “1” or “2”, please fill in 0.
2.c If the carrier type [CarrierType]= “3”, please fill in 0 or 1.
Special notes :
For KIOSK printing
(Please input the corresponding parameters as required, in addition to the request from our sales staff. )
1. To print the unannounced winning E-Invoice(ibon):
[Print]=1，[CarrierType]=””，[CustomerIdentifier]=””，[Donation]=0，
print only once (the E-Invoice cannot be reprinted in the future even if won)
2. To print the winning E-Invoice(iborn, FamiPort):
[Print]=0，[CarrierType]=1，[CustomerIdentifier]=””，[Donation]=0，print only once
3. If the remaining amount after allowance is NT $0, the E-Invoice can not be printed.
Donation String(1)
Required
- A mark to indicate whether this e-invoice is to be donated to charity organizations or not.
- 0 : Not donation
1 : For donation
Special notes :
If the Carrier Type [Carrier Type] or unified Business No. [CustomerIdentifier] has a value, then Donation is 0 which means do not donate.
LoveCode String(7)
- Donation code
- If customer chooses to donate E-Invoice, then the Donation Code of the donated needs to be entered to this parameter.
1. If the donation note [Donation ]= ‘1’ (Donation), then this parameter shall have value.
2. Donation code is limited to numerical digits, a minimum of three and maximum of seven. Content is designated as “Character Format”, first digit can be 0.
Special notes :
When using the LoveCode, please call Verifying the Existence of Love Code to check it first to avoid input errors.
Recommendation donation code
168001
OMG Charitable Foundation for Social Care
Setup up in 2009 with the goal of gathering the support of web users to deliver love and care to every corner of the society.
Our Foundation strives to: Support the schooling of students under the poverty line or that lack education resources, protection of strays and animals in general, support of the elderly and minority, emergency support, humanitarian aid, social charity events and ad support…and others.
CarrierType String(1)
- The type of carrier to store this e-invoice
- 1. If there is no carrier, please keep this parameter empty
2. If it is a ECPay E-Invoice carrier, then please fill in 1
3. If it is the customer’s citizen digital certificate, then please fill in 2
Special notes :
- When the printing note [Print]=1(print E-Invoice), please keep this parameter empty.
- If the printing note [Print]=0(Do not print E-Invoice) and the Unified Business No. [CustomerIdentifier] has value, this parameter cannot be empty
- Only E-Invoice with a Green World E-Invoice carrier ([CarrierType]=1) can be printed on ibon after winning.
CarrierNum String(64)
- The number of the carrier to store this e-invoice.
- When the carrier type [CarrierType]=””(no carrier), please empty the string, if the [CarrierType]=”1″(Green World E-Invoicecarrier), then please empty the string, the system will fill in the value automatically.
- When the carrier type[CarrierType]=”2″(customer’s citizen digital certificate), then please fill in a fixed length of 16 and sequence format of 2 alphabet and 14 numerical digits.
- When the carrier type[CarrierType]=”3″(customer’s cellphone bar code), then please fill in a fixed length of 8 and sequence format of 1 code slash “/” followed by a sequence of 7 numerical digits, cap-sized alphabet characters, and symbols such as【+】【-】【.】
Special noted :
- When the cellphone carrier has a plus sign, then there might be an error during interfacing verification, please change the plus sign to a blank character.
- If the carrier number changes to mobile barcode carrier (a barcode of serial number on mobile), please firstly call Verifying the Existence of Mobile Barcode.
TaxType String(1)
Required
- The Type of the tax
- When [InvTyp] is 07 (general tax), please enter 1, 2, 3 or 9 in this field.
If [InvType] is 08 (special tax), then please enter 3 or 4 in this field. - Parameter value explanation as follows:
1. If it should be taxed, please fill in 1.
2. If tax rate is zero, please fill in 2
3. If it is duty free, please fill in 3.
4. If it special tax computation, please fill in 4.
5. If it has a combined tax and duty free (Only when the register cannot discern, and has to be approved), please fill in 9.
SpecialTaxType Int
- Special Tax Type
- If [TaxType] is 1/2/9, please fill in 0.
If [TaxType] is 3, please fill in 8.
If [TaxType] is 4, and the parameter is required. - The parameter can fill in 1-8.
1: Saloons and tea rooms, coffee shops and bars offering companionship services：Tax rate is 25%.
2: Night clubs or restaurants providing entertaining show programs: Tax rate is 15%.
3: Banking businesses, insurance businesses, trust investment businesses, securities businesses, futures businesses, commercial paper businesses and pawn-broking businesses: Tax rate is 2%.
4: The sales amounts from reinsurance premiums shall be taxed at 1%.
5: Banking businesses, insurance businesses, trust investment businesses, securities businesses, futures businesses, commercial paper businesses and pawn-broking businesses: Tax rate is 5%
6: Core business revenues from the banking and insurance business of the banking and insurance industries (Applicable to sales after July 2014): Tax rate is 5%.
7: Core business revenues from the banking and insurance business of the banking and insurance industries (Applicable to sales after June 2014): Tax rate is 5%.
8: Duty free or non-output data.
SalesAmount Int
Required
- E-Invoice total amount (Tax included)
- Please designate full numbers, no decimals allowed.
- New Taiwan Dollars only.
- Amount cannot be 0.
InvoiceRemark String(200)
- E-Invoice Notation
- The parameter shall be exempted when calculating the check digit.
The product supports up to 200 items.
ItemSeq Int
Item Sequence Number
ItemName String(100)
Required
Item Name
ItemCount Number
Required
- Merchandise quantity
- It could be up to 8 integers and 2 decimals after the decimal point.
ItemWord String(6)
Required
Merchandise units
ItemPrice Number
Required
- Merchandise price
- It could be up to 8 integers and 7 decimals after the decimal point.
- The value of ItemPrice is tax-excluded if vat:0 (tax-excluded).
- The value of ItemPrice is tax-included if vat:1 (tax-included).
ItemTaxType String(1)
- Merchandise tax category
- 1: Should be taxed
2: Tax rate is zero
3: Duty Free
Special notes :
Preset is an empty string, when the tax category [TaxType] = 9, this parameter cannot be null.
ItemAmount Number
Required
- Merchandise total amount (tax-included).
- It could be up to 8 integers and 7 decimals after the decimal point.
Special notes :
- If vat= 1, and TaxType= 1 or 4:
ItemPrice(Tax)*ItemCount = ItemAmount(Tax)
ex: 500* 5= 2500 - If vat= 0, and TaxType= 1(Tax rate is 5%):
ItemPrice(duty free)*ItemCount*1.05= ItemAmount(Tax)
ex: 500* 5* 1.05= 2625
ItemRemark String(40)
Merchandise notation explanation
InvType String(2)
Required
- Type of letter track of e-invoice
- Possible values:
07: general tax (common business or e-commerce, which shall be no less than 5 %).
08: special tax (i.e. for special food and beverage services enterprises, such as night clubs or restaurants providing entertaining show programs, saloons and tea rooms and bars offering companionship services).
vat String(1)
- Whether merchandise unit price includes tax
- Preset as included tax price
1: Tax included
0: Tax not included
Example
Response format
- Content Type ：application/json
- HTTP Method ：POST
{
"MerchantID": "2000132",
"RelateNumber": "20181028000000001",
"InvoiceDate": "2018-10-28 23:12:34",
"CustomerID": "",
"CustomerIdentifier": "",
"CustomerName": "test name",
"CustomerAddr": "test address",
"CustomerPhone": "",
"CustomerEmail": "test@ecpay.com.tw",
"ClearanceMark": "1",
"Print": "1",
"Donation": "0",
"LoveCode": "",
"CarrierType": "",
"CarrierNum": "",
"TaxType": "1",
"SalesAmount": 100,
"InvoiceRemark": "remark",
"InvType": "07",
"vat": "1",
"Items": [
{
"ItemSeq": 1,
"ItemName": "item01",
"ItemCount": 1,
"ItemWord": "the",
"ItemPrice": 50,
"ItemTaxType": "1",
"ItemAmount": 50,
"ItemRemark": "item01_desc"
},
{
"ItemSeq": 2,
"ItemName": "item02",
"ItemCount": 1,
"ItemWord": "the",
"ItemPrice": 20,
"ItemTaxType": "1",
"ItemAmount": 20,
"ItemRemark": "item02_desc"
},
{
"ItemSeq": 3,
"ItemName": "item03",
"ItemCount": 3,
"ItemWord": "the",
"ItemPrice": 10,
"ItemTaxType": "1",
"ItemAmount": 30,
"ItemRemark": "item03_desc"
}
]
}
Response by ECPay (Json format)
PlatformID String(10)
MerchantID String(10)
Required
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": "..."
}
Message payload of Data (JSON format): please do AES decryption to the Data first and then perform 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 indicating whether the API is successfully executed or not.
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.
- Fix length of 10 characters
InvoiceDate String(20)
- Time of e-invoice created
- Only if the e-invoice is successfully issued or created, the value of the InvoiceDate will be responded. .
The format: yyyy-MM-dd HH:mm:ss
RandomNumber String(4)
- A unique of 4-digit number generated randomly of each e-invoice, which is used to prevent fake or counterfeiting.
- This value can be seen on a real e-invoice. Please see the chapter: searching e-invoice API, where there is an example to demonstrate (in the picture).
Example
{
"RtnCode": 1,
"RtnMsg": "Success",
"InvoiceNo": "20181028000000001",
"InvoiceDate": "2018-10-28 23:12:34",
"RandomNumber": "6866"
}
YAML
openapi: 3.1.0
info:
title: ECPay Void and Reissue Invoice API
version: 1.0.0
servers:
- url: https://einvoice-stage.ecpay.com.tw
description: Testing Environment
- url: https://einvoice.ecpay.com.tw
description: Production Environment
paths:
/B2CInvoice/VoidWithReIssue:
post:
summary: Void and Reissue Invoice
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- MerchantID
- RqHeader
- Data
properties:
PlatformID:
type: string
maxLength: 10
description: Platform ID for partnered platforms
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RqHeader:
type: object
required:
- Timestamp
properties:
Timestamp:
type: integer
description: Unix timestamp (GMT+8)
Data:
type: string
description: Encrypted data containing request details
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
PlatformID:
type: string
maxLength: 10
description: Platform ID for partnered platforms
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RpHeader:
type: object
properties:
Timestamp:
type: integer
description: Unix timestamp (GMT+8)
TransCode:
type: integer
description: Transmission code
TransMsg:
type: string
maxLength: 200
description: Transmission message
Data:
type: string
description: Encrypted data containing response details
components:
schemas:
requestBody.Data:
type: object
required:
- MerchantID
- VoidModel
- IssueModel
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
VoidModel:
type: object
required:
- InvoiceNo
- VoidReason
properties:
InvoiceNo:
type: string
maxLength: 10
description: Invoice number
VoidReason:
type: string
maxLength: 20
description: Reason for voiding the invoice
IssueModel:
type: object
required:
- RelateNumber
- InvoiceDate
- Print
- Donation
- TaxType
- SalesAmount
- Items
- InvType
- vat
properties:
RelateNumber:
type: string
maxLength: 30
description: Unique merchant number
InvoiceDate:
type: string
description: Invoice issue date in 'yyyy-MM-dd HH:mm:ss' format
CustomerID:
type: string
maxLength: 20
description: Customer ID
CustomerIdentifier:
type: string
maxLength: 8
description: Unified Business Number
CustomerName:
type: string
maxLength: 60
description: Customer name
CustomerAddr:
type: string
maxLength: 100
description: Customer address
CustomerPhone:
type: string
maxLength: 20
description: Customer phone number
CustomerEmail:
type: string
maxLength: 80
description: Customer email
ClearanceMark:
type: string
maxLength: 1
description: Customs clearance mark
Print:
type: string
maxLength: 1
description: Print mark
Donation:
type: string
maxLength: 1
description: Donation mark
LoveCode:
type: string
maxLength: 7
description: Donation code
CarrierType:
type: string
maxLength: 1
description: Carrier type
CarrierNum:
type: string
maxLength: 64
description: Carrier number
TaxType:
type: string
maxLength: 1
description: Tax type
SpecialTaxType:
type: integer
description: Special tax type
SalesAmount:
type: integer
description: Total invoice amount (including tax)
InvoiceRemark:
type: string
maxLength: 200
description: Invoice remark
Items:
type: array
items:
type: object
required:
- ItemName
- ItemCount
- ItemWord
- ItemPrice
- ItemAmount
properties:
ItemSeq:
type: integer
description: Item sequence number
ItemName:
type: string
maxLength: 100
description: Item name
ItemCount:
type: number
description: Item quantity
ItemWord:
type: string
maxLength: 6
description: Item unit
ItemPrice:
type: number
description: Item unit price
ItemTaxType:
type: string
maxLength: 1
description: Item tax type
ItemAmount:
type: number
description: Item total amount (including tax)
ItemRemark:
type: string
maxLength: 40
description: Item remark
InvType:
type: string
maxLength: 2
description: Invoice type
vat:
type: string
maxLength: 1
description: Whether the item price includes tax
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code
RtnMsg:
type: string
maxLength: 200
description: Response message
InvoiceNo:
type: string
maxLength: 10
description: New invoice number if reissued successfully
InvoiceDate:
type: string
description: Invoice issue date in 'yyyy-MM-dd HH:mm:ss' format
RandomNumber:
type: string
description: Random number for the invoice