Application Scenarios
Special Notes :
- After submission, the buyer needs to confirm the allowance details via email and click on the confirmation verification link (valid for 72 hours). The sales allowance is only issued when the verification link is clicked; you can cancel this allowance at any time before the buyer clicks the verification link.
- By using online consent for the allowance, you no longer need to mail the paper allowance form for the consumer to sign and keep a record. The ECPay system will log the buyer’s activity when they click the link to confirm consent for this particular allowance.
- Due to security considerations, no mail will be sent to the test environment (Stage), please conduct the mail sending test in the official environment (Prod).
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/AllowanceByCollegiate
- Production: https://einvoice.ecpay.com.tw/B2CInvoice/AllowanceByCollegiate
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
InvoiceNo String(30)
Required
- E-invoice number
- Fix length: 10
InvoiceDate String(10)
Required
- Date of e-invoice created
- 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 constomer 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 to 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 the allowance.
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 digits and 2 decimals.
ItemWord String(6)
Required
- Merchandise units
- For example, “個” in Chinese.
ItemPrice Number
Required
- Merchandise price (tax-included)
- It could be up to 8 digits and 7 decimals.
- 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] will need 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.
ReturnURL String
Required
- Merchant’s server URL to receive ECPay’s callback
- Once the customer agrees to the allowance by clicking the link in the email notification, the allowance will be issued, and ECPay will respond the payload of the allowance issued to this parameter.
Special notes : On receiveing the notification from ECPay, be sure to respond with the string ‘1|OK’.
Example
{
"MerchantID": 2000132,
"InvoiceNo": "UV11100015",
"InvoiceDate": "2019-09-17",
"AllowanceNotify": "E",
"CustomerName": "Test",
"NotifyMail": "test@ecpay.com.tw",
"NotifyPhone": "0912345678",
"AllowanceAmount": 50,
"Items": [
{
"ItemSeq": 1,
"ItemName": "item01",
"ItemCount": 1,
"ItemWord": "test",
"ItemPrice": 50,
"ItemTaxType": "2",
"ItemAmount": 50
}
],
"ReturnURL": "https://allowance.yoursite/Revice"
}
Response format
- Content Type :application/json
- HTTP Method :POST
Response by ECPay (Json format)
PlatformID String(10)
MerchantID String(10)
Required
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 success: the allowance number will be responded.
- If not, a null vlaue 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 sent in response.
IA_TempDate String(20)
- Date of issuing the allowance
- Online allowance order issuance termination date will be returned upon issuance success;“yyyy-MM-dd HH:mm:ss”;
- If the issuance failed then a blank value will be sent in response.
IA_TempExpireDate String(20)
- Online allowance agreement deadline
- Online allowance order issuance termination date will be returned upon issuance success;“yyyy-MM-dd HH:mm:ss”;
- If the issuance failed then a blank 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 sent in response.
Example
{
"RtnCode": 1,
"RtnMsg": "Success",
"IA_Allow_No": "1909181313013546",
"IA_Invoice_No": "UV11100019",
"IA_TempDate": "2019-09-18 13:13:23",
"IA_TempExpireDate": "2019-09-21 13:13:23",
"IA_Remain_Allowance_Amt": 0
}
Message payload of ReturnURL
RtnCode Int
- Return code
- 1 is success, others are failure.
RtnMsg String(200)
Response
IA_Allow_No String(16)
- Allowance order number
- If issing allowance success: the allowance number will be responded.
- If not, a null vlaue 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 sent in response.
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 blank 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 sent in response.
CheckMacValue String
The description is as follows.
- ECPay will response this parameter[CheckMacValue] after calculating the above parameters (RtnCode, RtnMsg, IA_Allow_No, IA_Invoice_No, IA_Date, and IIS_Remain_Allowance_Amt) with the Checksum Mechanism to ensure that the data is not tampered with in the transmission process.
- If vendors are concerned about data security, they can use the Checksum Mechanism to generate check codes for the received parameters (RtnCode, RtnMsg, IA_Allow_No, IA_Invoice_No, IA_Date, and IIS_Remain_Allowance_Amt) and compare them with this parameter[CheckMacValue] for consistency.
Example
RtnCode=1&RtnMsg=&IA_Allow_No=1909181313013546&IA_Invoice_No=UV11100019&IA_Date=2019-09-18 13:13:23&IIS_Remain_Allowance_Amt=0&CheckMacValue=72F8C0BB157D97E68FCAF5E79E8E142D6B346BEEB756288BC668A5AA2C34980E
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 Online Issue Allowance API
version: 1.0.0
servers:
- url: https://einvoice-stage.ecpay.com.tw
- url: https://einvoice.ecpay.com.tw
paths:
/B2CInvoice/AllowanceByCollegiate:
post:
summary: Online Issue Allowance
description: This API issues allowances electronically, notifying customers via email for confirmation.
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 (fixed value "E")
CustomerName:
type: string
maxLength: 60
description: Customer name
NotifyMail:
type: string
maxLength: 100
description: Notification email
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
ReturnURL:
type: string
maxLength: 200
description: URL to notify merchant after customer confirms 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_Allow_No:
type: string
maxLength: 16
description: Allowance number
IA_Invoice_No:
type: string
maxLength: 10
description: Invoice number
IA_TempDate:
type: string
description: Online allowance date (yyyy-MM-dd HH:mm:ss)
IA_TempExpireDate:
type: string
description: Online allowance expiration date (yyyy-MM-dd HH:mm:ss)
IA_Remain_Allowance_Amt:
type: number
description: Remaining allowance amount