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 tool that can record or link information to consumers’ e-invoices via electromagnetic technology incorporated into items such as mobile barcodes, membership cards, etc.) In some scenarios, some consumers prefer to donate e-invoices, so they choose to place the e-invoice number into the “Love Code,” which represents the charity organization they would like to donate the e-invoice to. A Love Code is a combination of Arabic numerals with at least three and up to seven numbers.
Notes:
1. When using a Love Code, the Love Code verification API can be called first to reduce the chances of input errors that could prevent successful donations.
2. The data for this API is sourced from the Ministry of Finance’s donation code database, which ECPay regularly downloads and updates.
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 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
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
- Response 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
1 indicates a successful query result, while all other codes represent failure.
RtnMsg String(200)
Return messages indicating whether the API is successfully executed or not.
IsExist String(1)
- If the response code [RtnCode] is 1 (successful), please refer to the value in this field to determine whether the donation code exists.
- Possible values:
Y: exist
N: not exist
OrganName String(100)
The value in this field will only be present if the parameter [IsExist] is Y (exist).
Example
{
"RtnCode": 1,
"RtnMsg": "成功取得查詢結果",
"IsExist": "Y",
"OrganName": "綠界科技"
}
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 Mobile Barcode Verification 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/CheckBarcode:
post:
summary: Mobile Barcode Verification
description: Verify the existence of a mobile barcode.
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
BarCode:
type: string
description: Mobile barcode (8 characters)
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code
RtnMsg:
type: string
description: Response message
OrganName:
type: string
description: Organization Name