Application Scenarios
(3) Trigger issuing
Merchants can use this function to issue the E-Invoice parameter to Green World in advance, where it would be stored by Green World temporarily, awaiting the confirmed time for issuance. The merchant can then trigger the issuance, the E-Invoice data will be stored at Green World prior to trigger, and based on the designated delay issuance day, once the time arrives the system will automatically issue and upload it to the Ministry of Finance and notify the customer that the E-Invoice has been issued. (If there is no designated issue time delay, then the E-Invoice shall be issued upon trigger)
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/TriggerIssue
- Production: https://einvoice.ecpay.com.tw/B2CInvoice/TriggerIssue
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
Tsr String(30)
Required
- Transaction Order
- Used as a basis tocall trigger after payment completion or delayed invoice issuance.
- Must be unique and non-repeated
PayType String(1)
Required
- Pay type
- Please fill in ‘2’ automatically in the case of Green World
Example
{
"MerchantID": "2000132",
"Tsr": "201909170001",
"PayType": "2"
}
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:
4000003: If DelayDay > 0, 4000003 indicates delayed issuing is success.
4000004: If DelayDay= 0, 4000004 indicates issuing is success.
Other values: fail.
RtnMsg String(200)
Return messages indicating whether the API is successfully executed or not.
OrderNumber String(30)
- E-Invoice issuance complete
- If issuance is a success, then the Tsr (Transaction Order) will be sent in response; If the issuance failed then a blank value will be sent in response.
Example
{
"RtnCode": 1,
"RtnMsg": "",
"Tsr": "201909170001"
}
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 Trigger Issue Invoice API
version: 1.0.0
servers:
- url: https://einvoice-stage.ecpay.com.tw
- url: https://einvoice.ecpay.com.tw
paths:
/B2CInvoice/TriggerIssue:
post:
summary: Trigger Issue Invoice
description: This API triggers the issuance of previously stored invoices after payment completion.
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
Tsr:
type: string
maxLength: 30
description: Transaction serial number
PayType:
type: string
maxLength: 1
description: Transaction type, should be '2'
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code indicating success or failure
RtnMsg:
type: string
maxLength: 200
description: Response message
Tsr:
type: string
maxLength: 20
description: Transaction serial number