Issuing Operations / Issuing E-invoice

Application Scenarios

In general, ECPay provides three types of issuing e-invoice, including: “Instant Issuing”, “Delayed Issuing” and “Triggered issuing.” The term “Instant Issuing”, compared to the last two (“Delayed Issuing” and “Triggered issuing”), refers to issue an invoice to your customer immediately at the time of creation. It can also be viewed as “general invoicing” or “common invoicing” since in most scenarios, merchants tend to use this method to invoice their customers. On the other hand, the last two methods do not issue an invoice immediately. They will be scheduled for some days later. The following introduces their usages and differences in between.

(1) Instant issuing/general issuing (instant invoicing):

You can issue an invoice to your customer immediately by calling the API (/B2CInvoice/Issue). Send the API request to ECPay, and if successful, ECPay will return the invoicing result and send a notification to both you and the customer. The next step, within 48 hours, ECPay, being as a value-adding center, will upload this e-invoice to the Platform of Ministry of Finance, which would greatly save your time on this duty.

Sample of selecting the carrier

One of the pros of e-invoice is it is paper-free, so you might wonder how customer will keep or save the e-invoice without any paper? In most scenarios of onling shopping, when the customer is doing checkout, some information is required, such as payment and shipping methods. At this step, it usually requires the customer to provide his/her own carrier to store the e-invoice. The definition of what a carrier is could be referred to chapter 2: Term Glossary. In general, on your website you can design your own template for customer to fill-in. You can provide two options for customer to select: either the customer’s carrier or ECPay’s carrier. If the customer selects the former, he/she needs to provide a mobile barcode or citizen digital certification. If the latter, the e-invoice will be stored in ECPay’s system, which is a series of alphanumericals automatically generated by ECPay. Following is an example of how you could design user interface on your site.

API URLs:

Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/Issue
Production: https://einvoice.ecpay.com.tw/B2CInvoice/Issue

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 perform AES encryption

MerchantID String(10)
Required

RelateNumber String(30)
Required

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

ChannelPartner String(1)

1:Shopee
The rest of the values are ignored.

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

ProductServiceId String(10)

The ID of Product-Service Types
This parameter must consist of English letters (A-Z, a-z) and numbers (0-9), and its length must be between 1 and 10 characters.
This parameter will only be processed when the internal backend switch is enabled; otherwise, this parameter will be ignored. To enable this feature, please contact your account representative.
Steps to follow are as outlined below:
1. Contact the relevant department to enable the multi-serial number feature for the B2C system.
2. In the vendor’s backend, under the Serial Number Category Management section, add product/service categories such as A0001-Tableware or A0002-Cleaning Supplies. You can refer to the Serial Number Category Management chapter in the e-Invoice System User Manual for more details.
3. In the vendor’s backend, under the Serial Number and Allocation Settings section, add serial number allocations. You can refer to the Serial Number and Allocation Settings chapter in the e-Invoice System User Manual for further instructions.
4. When issuing invoices via the Invoice API, use the previously set A0001 or A0002 from the vendor’s backend as the parameter for [ProductServiceID] to complete the invoicing process.

CustomerIdentifier String(8)

Tax ID number (VAT number) of customer’s company
According to the latest announcement from the Ministry of Finance, there have been some adjustments made to the verification method for the Unified Business Number. You can click on the following link to view:
[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).

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 2 (zero tax) or 9 (a mix of taxable and zero 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 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
If the print parameter [Print]=1 (indicating printing is required), and carrier is also needed, then it can only carry 3 denoting E-Invoice cellphone carrier. If no carrier is needed, please pass in an empty string.
If it is a ECPay E-Invoice carrier, then please fill in 1
If it is the customer’s citizen digital certificate, then please fill in 2
If customer use E-Invoice cellphone carrier, please fill in 3.

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:
a. If it should be taxed, please fill in 1.
b. If tax rate is zero, please fill in 2
c. If it is duty free, please fill in 3.
d. If it special tax computation, please fill in 4.
e. If it has a combined tax and duty free, please fill in 9(has to be approved).
ECPay tax calculation method:
For regular invoices (non-combined tax, non-special):
( Invoice amount / 1.05 ) * 0.05, rounded to the nearest whole number.
For combined tax invoices:
( Total sum of taxable items / 1.05 ) * 0.05, rounded to the nearest whole number.

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.

InvoiceRemark String(200)

E-Invoice Notation
The parameter shall be exempted when calculating the check digit.

Items Array[Object]

The product supports up to 999 items.

ItemSeq Int

Item Sequence Number
Please input 1~999 integer for this parameter.

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
The value of ItemPrice is tax-excluded if vat:0 (tax-excluded), it could be up to 7 integers and 5 decimals after the decimal point.
The value of ItemPrice is tax-included if vat:1 (tax-included), it could be up to 8 integers and 7 decimals after the decimal point.

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

				
					{
    "MerchantID": "2000132",
    "RelateNumber": "20181028000000001",
    "CustomerIdentifier": "53538851",
    "CustomerName": "%e7%b6%a0%e7%95%8c%e7%a7%91%e6%8a%80%e8%82%a1%e4%bb%bd%e6%9c%89%e9%99%90%e5%85%ac%e5%8f%b8",
    "CustomerAddr": "%e8%87%ba%e5%8c%97%e5%b8%82%e5%8d%97%e6%b8%af%e5%8d%80%e4%b8%89%e9%87%8d%e8%b7%af19-2%e8%99%9f56%e6%a8%93-2+(D%e6%a3%9f)",
    "CustomerPhone": "0912345678",
    "CustomerEmail": " abc%40ecpay.com.tw ",
    "ClearanceMark": "1",
    "Print": "0",
    "Donation": "1",
    "LoveCode": "168001",
    "CarrierType": "",
    "CarrierNum": "",
    "TaxType": "1",
    "SalesAmount": 300,
    "InvType": "07",
    "vat": "1"
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "%E5%96%AE%E4%BD%8D1%7C%E5%96%AE%E4%BD%8D2%7C%E5%96%AE%E4%BD%8D3",
            "ItemPrice": 50,
            "ItemTaxType": "1",
            "ItemAmount": 50,
            "ItemRemark": "item01_desc"
        },
        {
            "ItemSeq": 2,
            "ItemName": "item02",
            "ItemCount": 1,
            "ItemWord": "%E5%96%AE%E4%BD%8D1%7C%E5%96%AE%E4%BD%8D2%7C%E5%96%AE%E4%BD%8D3",
            "ItemPrice": 20,
            "ItemTaxType": "1",
            "ItemAmount": 20,
            "ItemRemark": "item02_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": "..."
}

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.

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 could be seen on a real e-invoice, please see the chapter: searching e-invoice API, where there is an example to demonstrate (in picture.)

Example

				
					{
  "RtnCode": 1,
  "RtnMsg": "開立發票成功",
  "InvoiceNo": "UV11100012",
  "InvoiceDate": "2019-09-17 17:17:31",
  "RandomNumber": "6868"
}

YAML

The provided YAML file is used to define the configuration, structure, operations, and infrastructure management information of the API, making it easier for developers to understand and use the API.

				
					openapi: 3.1.0
info:
  title: ECPay General Invoice Issuance API
  version: 1.0.0
servers:
  - url: https://einvoice.ecpay.com.tw
    description: Production Environment
  - url: https://einvoice-stage.ecpay.com.tw
    description: Testing Environment
paths:
  /B2CInvoice/Issue:
    post:
      summary: General Invoice Issuance
      description: Issue an invoice immediately.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - MerchantID
                - RqHeader
                - Data
              properties:
                PlatformID:
                  type: string
                  description: Platform identifier (optional)
                MerchantID:
                  type: string
                  description: Merchant identifier
                RqHeader:
                  type: object
                  properties:
                    Timestamp:
                      type: number
                      description: Timestamp of the request
                Data:
                  type: string
                  description: Encrypted data in JSON format
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  PlatformID:
                    type: string
                    description: Platform identifier
                  MerchantID:
                    type: string
                    description: Merchant identifier
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: number
                        description: Timestamp of the response
                  TransCode:
                    type: integer
                    description: Transmission code
                  TransMsg:
                    type: string
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted data in JSON format
        '400':
          description: Invalid request
        '500':
          description: Server error
components:
  schemas:
    requestBody.Data:
      type: object
      properties:
        MerchantID:
          type: string
          description: Merchant identifier
        RelateNumber:
          type: string
          description: Unique merchant-defined number
        CustomerID:
          type: string
          description: Customer identifier
        CustomerIdentifier:
          type: string
          description: Unified business number
        CustomerName:
          type: string
          description: Customer name
        CustomerAddr:
          type: string
          description: Customer address
        CustomerPhone:
          type: string
          description: Customer phone number
        CustomerEmail:
          type: string
          description: Customer email
        ClearanceMark:
          type: string
          description: Clearance mark
        Print:
          type: string
          description: Print mark (0 = no print, 1 = print)
        Donation:
          type: string
          description: Donation mark (0 = no donation, 1 = donation)
        LoveCode:
          type: string
          description: Donation code
        CarrierType:
          type: string
          description: Carrier type
        CarrierNum:
          type: string
          description: Carrier number
        TaxType:
          type: string
          description: Tax type
        SalesAmount:
          type: number
          description: Total sales amount
        InvoiceRemark:
          type: string
          description: Invoice remark
        Items:
          type: array
          items:
            type: object
            properties:
              ItemSeq:
                type: integer
                description: Item sequence number
              ItemName:
                type: string
                description: Item name
              ItemCount:
                type: number
                description: Item quantity
              ItemWord:
                type: string
                description: Item unit
              ItemPrice:
                type: number
                description: Item price
              ItemTaxType:
                type: string
                description: Item tax type
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          description: Response message
        InvoiceNo:
          type: string
          description: Invoice number
        InvoiceDate:
          type: string
          format: date
          description: Invoice date (yyyy-MM-dd HH:mm:ss)
        RandomNumber:
          type: string
          description: Random number for the invoice

Green World