Data Verification / Verifying the Existence of Love Code

Application Scenarios

Merchants can call this API to check if the Love Code exists before issuing the e-invoice.
Most consumers have already come to know what an e-invoice is, and they also present a carrier when making payments (a carrier is a form of tool which is able to record or link the information to consumers’ e-invoices via electromagnetic technology incorporated into items such as, mobile barcodes, membership cards, and etc.) But in some scenarios, some consumers have the habit to donate e-invoices, so they will choose to place the e-invoice number into the “Love Code”, which represents the charity organization that they would like to donate the e-invoice to. A Love Code is a combination of Arabic numerals with at least three numbers and up to seven numbers.

Notes:
1. When using a love code, the love code verification API can be called first for checking, to reduce the chances of input errors that could prevent successful donations.
2. This API interacts with the Ministry of Finance’s system for data verification. However, the Ministry of Finance’s system may undergo unexpected maintenance, which can impact the stability and availability of the API. Therefore, it is recommended not to rely on this API as a necessary verification mechanism before issuing invoices. Consider it as an auxiliary verification tool to avoid disrupting the normal issuance of invoices.

API URLs:

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

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

LoveCode String(7)
Required

A unique code of the charity organization
Only numerals acceptable. At least three numbers and up to seven numbers. The first digit could be 0.

Example

				
					{
   "MerchantID": 2000132,
   "LoveCode": "1680000"
}

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.

Special notes :

This field value represents the result of the call transaction operation and does not indicate the existence of a mobile barcode result.
9000001: Failed to call the Ministry of Finance API.
This indicates that the Ministry of Finance system is currently under maintenance and unable to verify. Please try again later.

RtnMsg String(200)

Return messages to indicate whether the API is successfully executed or not.

IsExist String(1)

A response value to indicate whether the Love Code exists
Possible values:
Y: Exist
N: Not exist

Example

				
					{
  "RtnCode": 1,
  "RtnMsg": "",
  "IsExist": "Y"
}

Green World