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

MerchantID String(10)
Required

SearchType String(1)
Required

Type of search
Values include:
0: to search by AllowanceNo.
1: to search by InvoiceNo and the date of creating the e-invoice
2: to search 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
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.

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 :

The preset is an empty string. When the tax category [TaxType] = 9, this parameter cannot be null.
This parameter type is for singular item merchandise; For multiple items of merchandise, please separate with the character “|”.
When [TaxType]=9, [ItemTaxType] will need to specify the tax rate of each merchandise. There should be at least one item with a tax rate of 1 (To be taxed) and another with a tax rate of 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"
}

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 Query Allowance Details API
  version: 1.0.0
servers:
  - url: https://einvoice-stage.ecpay.com.tw
    description: Testing Environment
  - url: https://einvoice.ecpay.com.tw
    description: Production Environment
paths:
  /B2CInvoice/GetAllowanceList:
    post:
      summary: Query Allowance Details
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - MerchantID
                - RqHeader
                - Data
              properties:
                PlatformID:
                  type: string
                  maxLength: 10
                  description: Platform ID for partnered platforms
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                RqHeader:
                  type: object
                  required:
                    - Timestamp
                  properties:
                    Timestamp:
                      type: integer
                      description: Unix timestamp (GMT+8)
                Data:
                  type: string
                  description: Encrypted data containing request details
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  PlatformID:
                    type: string
                    maxLength: 10
                    description: Platform ID for partnered platforms
                  MerchantID:
                    type: string
                    maxLength: 10
                    description: Merchant ID
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: integer
                        description: Unix timestamp (GMT+8)
                  TransCode:
                    type: integer
                    description: Transmission code
                  TransMsg:
                    type: string
                    maxLength: 200
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted data containing response details
components:
  schemas:
    requestBody.Data:
      type: object
      required:
        - MerchantID
        - SearchType
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        SearchType:
          type: string
          maxLength: 1
          description: Search type (0 is Allowance number, 1 is Invoice number and issue date, 2 is Invoice number and allowance date)
          enum: 
            - 0
            - 1
            - 2
        AllowanceNo:
          type: string
          maxLength: 16
          description: Allowance number (required if SearchType is 0)
        InvoiceNo:
          type: string
          maxLength: 10
          description: Invoice number (required if SearchType is 1 or 2)
        Date:
          type: string
          description: Date in 'yyyy-MM-dd' or 'yyyy/MM/dd' format (required if SearchType is 1 or 2)
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        AllowanceInfo:
          type: array
          items:
            type: object
            properties:
              ChannelPartner:
                type: string
                maxLength: 1
                description: Channel partner ID
              IA_Allow_No:
                type: string
                maxLength: 16
                description: Allowance number
              IA_Check_Send_Mail:
                type: string
                maxLength: 1
                description: Allowance notification (S is SMS, E is Email, A is Both, N is None)
                enum: 
                  - S
                  - E
                  - A
                  - N
              IA_Date:
                type: string
                description: Allowance date in 'yyyy-MM-dd HH:mm:ss' format
              Items:
                type: array
                items:
                  type: object
                  properties:
                    ItemSeq:
                      type: integer
                      description: Item sequence number
                    ItemName:
                      type: string
                      maxLength: 100
                      description: Item name
                    ItemCount:
                      type: number
                      description: Item quantity
                    ItemWord:
                      type: string
                      maxLength: 6
                      description: Item unit
                    ItemPrice:
                      type: number
                      description: Item unit price
                    ItemRateAmt:
                      type: number
                      description: Item tax amount
                    ItemTaxType:
                      type: string
                      maxLength: 1
                      description: Item tax type (1 is Taxable, 2 is Zero tax rate, 3 is Exempt)
                    ItemAmount:
                      type: number
                      description: Item total amount
              IA_IP:
                type: string
                maxLength: 20
                description: Allowance IP
              IA_Identifier:
                type: string
                maxLength: 10
                description: Buyer identifier (0000000000 if none)
              IA_Invalid_Status:
                type: string
                maxLength: 1
                description: Allowance invalidation status (1 is Invalid, 0 is Not invalid)
              IA_Invoice_Issue_Date:
                type: string
                description: Invoice issue date in 'yyyy-MM-dd HH:mm:ss' format
              IA_Invoice_No:
                type: string
                maxLength: 10
                description: Invoice number
              IA_Mer_ID:
                type: string
                maxLength: 10
                description: Merchant ID
              IA_Send_Mail:
                type: string
                maxLength: 100
                description: Notification email
              IA_Send_Phone:
                type: string
                maxLength: 100
                description: Notification phone number
              IA_Tax_Amount:
                type: number
                description: Total tax amount
              IA_Tax_Type:
                type: string
                maxLength: 1
                description: Tax type (1 is Taxable, 2 is Zero tax rate, 3 is Exempt, 4 is Taxable (special rate))
              IA_Total_Amount:
                type: number
                description: Total amount (excluding tax)
              IA_Total_Tax_Amount:
                type: number
                description: Total amount (including tax)
              IA_Upload_Date:
                type: string
                description: Upload date in 'yyyy-MM-dd HH:mm:ss' format
              IA_Upload_Status:
                type: string
                maxLength: 1
                description: Allowance upload status (1 is Uploaded, 0 is Not uploaded)
              IIS_Customer_Name:
                type: string
                maxLength: 60
                description: Buyer name

Green World