Issuing Operations / Invalidating Allowance (Issuing general allowance)

Application Scenarios

Same as the invalidating e-invoice API, merchants can use this function to cancel the allowance. When the API request is successful, ECPay will upload the data of the allowance ticket that is to be invalidated or to be cancelled to the Platform of Ministry of Finance on the next day. If the allowance ticket is successfully invalidated, ECPay will notify the customer.

Special Notes :

After 23:59:59 of the 13th of each odd month ( i.e. January, March, May, July, September and November), because the regular routine of reporting to Ministry of Finance is complete, allowance tickets issued in two months earlier cannot be invalidated or cancelled. For example, on March 14th, the allowance ticket issued in January and February cannot be invalidated.

API URLs:

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

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

MerchantID String(10)
Required

InvoiceNo String(10)
Required

Number of e-invoice
Fix length: 10

AllowanceNo String(16)
Required

Number of allowance
Fix length: 16.

Reason String(20)
Required

Reason for cancellation

Example

				
					{
   "MerchantID": 2000132,
   "InvoiceNo": "AA123456",
   "AllowanceNo": "2016022615195209",
   "Reason": ""
}

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.

IA_Invoice_No String(10)

Number of e-invoice
Possible values:
If the cancellation is successful, the number of e-invoice will be returned.
If not successful, no value will be returned.

Example

				
					{
  "RtnCode": "1",
  "RtnMsg": "",
  "IA_Invoice_No": "AA123456"
}

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 Void Allowance API
  version: 1.0.0
servers:
  - url: https://einvoice-stage.ecpay.com.tw
  - url: https://einvoice.ecpay.com.tw
paths:
  /B2CInvoice/AllowanceInvalid:
    post:
      summary: Void Allowance
      description: This API voids previously issued allowances.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - MerchantID
                - RqHeader
                - Data
              properties:
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                RqHeader:
                  type: object
                  required:
                    - Timestamp
                  properties:
                    Timestamp:
                      type: integer
                      description: Unix timestamp in GMT+8
                Data:
                  type: string
                  description: Encrypted data
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  MerchantID:
                    type: string
                    description: Merchant ID
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: integer
                        description: Unix timestamp in GMT+8
                  TransCode:
                    type: integer
                    description: Transmission code indicating success or failure
                  TransMsg:
                    type: string
                    maxLength: 200
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted response data
components:
  schemas:
    requestBody.Data:
      type: object
      required:
                - MerchantID
                - InvoiceNo
                - AllowanceNo
                - Reason
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        InvoiceNo:
          type: string
          maxLength: 10
          description: Invoice number
        AllowanceNo:
          type: string
          maxLength: 16
          description: Allowance number
        Reason:
          type: string
          maxLength: 20
          description: Reason for voiding the allowance
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code indicating success or failure
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        IA_Invoice_No:
          type: string
          maxLength: 10
          description: Invoice number

Green World