B2C E-Invoice API Document

Searching Operations / Searching Allowance

Application Scenarios

This API provides the function of searching a particular allowance ticket.

API URLs:

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

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

MerchantID String(10)
Required

SearchType String(1)
Required

  • Type of search
  • Values include:
    0: to search by AllowanceNo.
    1: to seach by InvoiceNo and the date of creating the e-invoice
    2: to seach by InvoiceNo and the date of creating the allowance ticket.

AllowanceNo String(16)
Required

  • Number of allowance ticket
  • Fix length: 16

InvoiceNo String(10)
Required

  • Number of e-invoice
  • Fix length: 10

Date String(10)

  • The format: yyyy-MM-dd
  • If SearchType:1, this should be the date of creating e-invoice.
    If SearchType:2, this should be the date of creating allowance ticket.

Example

				
					{
  "MerchantID": 2000132,
  "SearchType": "0",
  "AllowanceNo": "2019091719477262"
}

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.

AllowanceInfo Array

List of the allowance ticket

Example

				
					{
   "RtnCode": 1,
   "RtnMsg": "成功",
   "AllowanceInfo": [
        {…},
        {…}
    ]
}

Message payload of AllowanceInfo (Json format)

ChannelPartner String(1)

1:Shopee

IA_Allow_No String(16)

  • Allowance order number
  • Fix length: 16

IA_Check_Send_Mail String(1)

  • Type of allowance notification
  • Possible values:
    S: by SMS
    E: by email
    A: both by SMS and email
    N: No notifications

IA_Date String(20)

  • Allowance time
  • The format: yyyy-MM-dd HH:mm:ss
Items Array[Object]

ItemSeq Int

Item Sequence Number

ItemName String(100)

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

ItemCount Number

  • Merchandise quantity
  • It could be up to 8 integers and 2 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

ItemRateAmt Number

Merchandise Sales Tax amount

ItemTaxType String(1)

  • Merchandise tax category
  • 1: Should be taxed
    2: Tax rate is zero
    3: Duty Free

❗ Special notes : 

  1. Preset is an empty string, when the tax category [TaxType] = 9, this parameter cannot be null.
  2. This parameter type is for singular item merchandise; For multiple items of merchandise, please separate with the character “|”.
  3. When [TaxType]=9, [ItemTaxType] will need to discern the tax rate of each merchandise, amongst them should be at least 1 item that is 1(To be taxed) and another as 2(Duty Free) or 3(Tax rate is zero). Implying the combined tax rate E-Invoice can only be: 1|3(To be taxed and Duty Free) or 1|2(To be taxed and tax rate is zero).

ItemAmount Number

Merchandise total amount

IA_IP String(20)

Allowance IP

IA_Identifier String(10)

  • Customer’s Tax ID
  • 0000000000 implies that there is no Tax ID

IA_Invalid_Status String(1)

  • Allowance invalidation status
  • 1: Allowance order have been invalidated
    0: Allowance order not yet invalidated

IA_Invoice_Issue_Date String(20)

  • E-Invoice issuance time
  • Format is “yyyy-MM-dd HH:mm:ss”

IA_Invoice_No String(10)

  • E-Invoice number
  • Fix length of 10 characters

IA_Mer_ID String(10)

Merchant Code

IA_Send_Mail String(100)

  • Notify Mail
  • Email in which notification is sent to

IA_Send_Phone String(100)

  • Notify cellphone number
  • Cellphone number in which notification is sent to

IA_Tax_Amount Int

Total Sales Tax amount

IA_Tax_Type String(1)

  • Tax category
  • 1: Should be taxed
    2: Tax rate is zero
    3: Duty Free

IA_Total_Amount Int

Total amount (Not including tax)

IA_Total_Tax_Amount Int

E-Invoice total amount (Tax included)

IA_Upload_Date String(20)

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

IA_Upload_Status String(1)

  • Allowance upload status
  • 1: Upload complete
    0: Not yet uploaded

IIS_Customer_Name String(30)

Customer’s name

Example

				
					{
    "ChannelPartner": "",
    "IA_Allow_No": "2019091719477262",
    "IA_Check_Send_Mail": "E",
    "IA_Date": "2019-09-17 19:47:19",
    "IA_IP": "0",
    "IA_Identifier": "0000000000",
    "IA_Invalid_Status": "1",
    "IA_Invoice_Issue_Date": "2019-09-17 19:47:05",
    "IA_Invoice_No": "UV11100016",
    "IA_Mer_ID": "2000132",
    "IA_Send_Mail": "test@ecpay.com.tw",
    "IA_Send_Phone": "0912345678",
    "IA_Tax_Amount": 2,
    "IA_Tax_Type": "1",
    "IA_Total_Amount": 48,
    "IA_Total_Tax_Amount": 50,
    "IA_Upload_Date": "",
    "IA_Upload_Status": "0",
    "IIS_Customer_Name": "Test",
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "Test",
            "ItemPrice": 50,
            "ItemTaxType": "1",
            "ItemRateAmt": 2,
            "ItemAmount": 50
        }
    ],
    "RtnCode": 1,
    "RtnMsg": "Success"
}

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

Green World