Data Verification / Verifying the Existence of Mobile Barcode

Application Scenarios

Merchants can call this API to check if the mobile barcode exists before issuing the e-invoice. A mobile barcode enables the consumer to record or save the information of the e-invoice. For the definition of the carrier, please refer to chapter 2: Glossary.

Notes:
1. If the carrier number is a mobile barcode carrier, the mobile barcode verification API can be called first for checking. If there is an error in the mobile barcode, it may result in the invoice not being properly attributed to the account.
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 activities, which can affect the stability and availability of the API. Therefore, it is advised not to use this API as the sole verification mechanism before issuing an invoice. It should be considered an auxiliary verification tool to avoid interrupting the normal issuance of invoices.

API URLs:

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

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 later 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 the server with another server in 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 first and then perform AES encryption

MerchantID String(10)
Required

BarCode String(7)
Required

A mobile barcode that a consumer has
Sequence format should be 1 code slash “/” followed by a combination of 7 numerals, English alphabets and special characters “+”, “-“, “.” Only half-width is acceptable.

Special notes : Some mobile barcodes have a plus symbol (+), which might cause an error when making an API request. Please replace it with an empty character (i.e. space or blank).

Example

				
					{
   "MerchantID": 2000132,
   "BarCode": "/1234567"
}

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

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 indicating whether the API is successfully executed or not.

IsExist String(1)

A response value to indicate whether the mobile barcode exists.
Possible values:
Y: Exist
N: Not exist

Example

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

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
        IsExist:
          type: string
          description: Mobile barcode existence status (Y or N)

Green World