Issuing Operations / Issuing Allowance / Issuing general allowance

Application Scenarios

In general, ECPay provides two methods to issue the allowance when a sales return happens. The first one is general allowance, which requires merchants or sellers to get the agreement from the customer first (not by using ECPay’s system) and then to send an API request to ECPay to issue an allowance. The other one is sending an API request to ECPay and ECPay will send an e-mail notification to the customer to get his/her agreement. In the email notification there is a link and once the customer clicks the link, an allowance will be issued instantly.

Special Notes：Per regulations from the Ministry of Finance, after transmitting paper allowance information via API, it is mandatory to obtain confirmation of the allowance slip details from the buyer. Consequently, you must mail the physical allowance slip to the consumer for their signature and then retain it in your own records, in preparation for sporadic audits by the supervisory authorities.

API URLs:

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

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 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

InvoiceNo String(30)
Required

E-invoice number
Fixed length: 10

InvoiceDate String(10)
Required

Date of e-invoice creation
The format: yyyy-MM-dd

CustomerName String(60)

The name of the customer you are invoicing.
Only numbers and Chinese or English characters are acceptable.

NotifyMail String(100)

Customer’s mail address to receive the notification
Required and should have value if AllowanceNotify : E (i.e. to notify the customer by email.)
2. Only valid email formats (i.e. aa@bb.cc) are accepted.
3. NotifyMail can be more than one email address and using the semicolon (;) to separate different email address. For example: aaa@ecpay.com.tw; bbb@ecpay.com.tw

NotifyPhone String(20)

Customer’s mobile number to receive the notification
Required if AllowanceNotify: S (receiving notifications by SMS).
Only numbers are acceptable.

AllowanceAmount Int
Required

Total amount of this allowance (tax included)

Special Notes:
The total amount of the allowance should be greater than $0
1. If the invoice has not been allowanced, it should be less than or equal to the total amount of the original invoice
2. If this invoice has been allowanced, it should be less than or equal to the remaining amount of allowance

Items Array[Object]

ItemSeq Int

Required

Item Sequence Number

ItemName String(100)
Required

Item Name
Value is required; empty string is not accepted.

ItemCount Number
Required

Merchandise quantity
It could be up to 8 integers and 2 decimals after the decimal point.

ItemWord String(6)
Required

Merchandise units
For example, “個” in Chinese.

ItemPrice Number
Required

Merchandise price (tax-included)
It could be up to 8 integers and 7 decimals after the decimal point.
The value of ItemPrice is tax-excluded if vat:0 (tax-excluded).
The value of ItemPrice is tax-included if vat:1 (tax-included).

ItemTaxType String(1)

Merchandise tax category
1: Should be taxed
2: Tax rate is zero
3: Duty Free

Special notes :

Preset is an empty string, when the tax category [TaxType] = 9, this parameter cannot be null.
When [TaxType]=9, [ItemTaxType] needs to discern the tax rate of each merchandise, amongst them should be at least 1 item that is 1(To be taxed) and another as 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
Required

Merchandise total amount (tax-included).
This parameter supports up to 8-digit integer and 7-digit decimal.
Assuming A = [ItemPrice] x [ItemCount], A and [ItemAmount] are allowed a discrepancy within 1 unit.
The sum of the [ItemAmount] for each Item must equal the total amount allowance [AllowanceAmount].
The value of the amount should be tax included.

Special notes :

Integer only because of the law and regulations of MOF in Taiwan.

Example

				
					{
    "MerchantID": "2000132",
    "InvoiceNo": "UV11100013",
    "InvoiceDate": "2019-09-17",
    "AllowanceNotify": "E",
    "CustomerName": "%e7%b6%a0%e7%95%8c%e7%a7%91%e6%8a%80%e8%82%a1%e4%bb%bd%e6%9c%89%e9%99%90%e5%85%ac%e5%8f%b8",      "NotifyMail": "test@ecpay.com.tw", 
    "NotifyPhone": "0912345678",
    "AllowanceAmount": 50, 
    "Items": [{ 
             "ItemSeq": 1,
             "ItemName": "item01", 
             "ItemCount": 1, 
             "ItemWord": "件",
             "ItemPrice": 50, 
             "ItemTaxType": "2",
             "ItemAmount": 50 
             }] 
    }

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_Allow_No String(16)

Allowance order number
If issuing allowance is successful: the allowance number will be responded.
If not, a null value will be responded.

IA_Invoice_No String(10)

E-Invoice number
If the issuance is successfully completed then the original set of E-Invoice number will be sent in return;
If the issuance failed then a blank value will be returned.

IA_Date String(20)

Allowance time
Allowance order issuance time will be returned upon issuance success;
Return format is “yyyy-MM-dd HH:mm:ss”;
If the issuance failed then a null value will be sent in response.

IA_Remain_Allowance_Amt Int

Remaining amount of allowance
Remaining amount of allowance will be returned upon issuance success;
If the issuance failed then a blank value will be returned.

Example

				
					{
    "IA_Allow_No": "2019091717363987",
    "IA_Invoice_No": "UV11100013",
    "IA_Date": "2019-09-17 17:36:18",
    "IA_Remain_Allowance_Amt": 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 General Issue Allowance API
  version: 1.0.0
servers:
  - url: https://einvoice-stage.ecpay.com.tw
  - url: https://einvoice.ecpay.com.tw
paths:
  /B2CInvoice/Allowance:
    post:
      summary: General Issue Allowance
      description: This API issues allowances for discrepancies such as quality or specification issues.
      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
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        InvoiceNo:
          type: string
          maxLength: 10
          description: Invoice number
        InvoiceDate:
          type: string
          format: date
          description: Invoice date (yyyy-MM-dd or yyyy/MM/dd)
        AllowanceNotify:
          type: string
          maxLength: 1
          description: Notification type (S=SMS, E=Email, A=All, N=None)
        CustomerName:
          type: string
          maxLength: 60
          description: Customer name
        NotifyMail:
          type: string
          maxLength: 100
          description: Notification email
        NotifyPhone:
          type: string
          maxLength: 20
          description: Notification phone number
        AllowanceAmount:
          type: number
          description: Total allowance amount (including tax)
        Items:
          type: array
          properties:
              ItemSeq:
                type: integer
                description: Item sequence
              ItemName:
                type: string
                maxLength: 100
                description: Item name
              ItemCount:
                type: number
                description: Item count
              ItemWord:
                type: string
                maxLength: 6
                description: Unit
              ItemPrice:
                type: number
                description: Item price
              ItemAmount:
                type: number
                description: Item amount
              ItemTaxType:
                type: string
                maxLength: 1
                description: Item tax type
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code indicating success or failure
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        IA_Allow_No:
          type: string
          maxLength: 16
          description: Allowance number
        IA_Invoice_No:
          type: string
          maxLength: 10
          description: Invoice number
        IA_Date:
          type: string
          description: Allowance issue date (yyyy-MM-dd HH:mm:ss)
        IA_Remain_Allowance_Amt:
          type: number
          description: Remaining allowance amount

Green World