Scenarios
- B2B E-invoices shall notify the both parties(buyer/seller) of any change in invoice status, and the buyer/seller(Business Entity) may use this API to send E-invoices notifications(It can also be processed through the merchant’s admin website).
- Green World will notify both parties with the contact information provided at the time of invoice creation.
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2BInvoice/Notify
- Production: https://einvoice.ecpay.com.tw/B2BInvoice/Notify
Special Notes :
- On Stage environment, ECPay will not send any notification. Any notification that should be sent to a specific e-mail address must be set firstly on Merchant’s Admin Website.
HTTPS format
- Content Type ：application/json
- HTTP Method ：POST
Request by Merchant (Json format)
PlatformID String(10)
- Platform merchant ID
- This parameter is provided by ECPAY to the platform vendor for project cooperation, please bring in the MerchantID bound with the platform vendor.
- Please leave empty for general vendor.
- When the platform vendor uses the MerchantID field, it can only bring in the MerchantID that has been bound as a sub-store, otherwise it will cause a failure.
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 be failed. 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 firstly and then do AES encryption
MerchantID String(10)
Required
InvoiceNumber String(10)
Required
E-Invoice number
InvoiceDate String(20)
Required
The format is yyyy-mm-dd
AllowanceNo String(16)
Allowance Code
Special Notes : The number length of the allowance number is fixed to 16 digits. NotifyMail String(200)
Required
Notify Mail
- 1. Please enter the standard email format.
- 2. This field can be populated with more than one e-mail address. Please separate each e-mail address by semicolon.
- The regular expression for format validation is
^((([A–Za–z]|\d|[!#\$%&‘\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([A-Za-z]|\d|[!#\$%&’\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?$
Notified String(1)
Required
Notify Target
- C: Send notifications to customers
- M: Send notifications to merchants
- A: All send notifications.
InvoiceTag String(1)
Required
Type of notification
- Exchange Mode:
- 1:Issue
- 2:Cancel
- 3:Reject
- 4:Allownace
- 5:Cancel Allowance
- 6:Issue Confirm
- 7:Cancel Confirm
- 8:Reject Confirm
- 9:Allowance Confirm
- 10:Cancel Allowance Confirm
- Certification Mode:
- 1:Issue
- 2:Cancel
- 3:Reject
- 4:Allowance
Special Notes :
- Under the Certification Mode, only the buyer is allowed to cancel the allowance in accordance with the Ministry of Finance documentation.
- Therefore, using the notice of the 5.Cancel allowance from the seller’s point of view will result in the receipt of a Buyer/Seller error
- The practical implication is that no further notice is required to be given to the Buyer who cancel the allowance.
Notified String(1)
Required
Delivery party
- Possible values:
- C: Deliver notification to customer
- M: Deliver notification to merchant
- A: Deliver both notifications
Example
{
"MerchantID": "2000132",
"InvoiceDate": "2019-09-04",
" InvoiceNumber": "VG11000000",
" NotifyMail": "abc5678@gmail.com; def5678@gmail.com ",
" InvoiceTag": 1,
" Notified": "C"
}
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
- Responde 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 firstly and then do 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 to indicate whether the API is successfully executed or not.
Example
{
"RtnCode": 1,
"RtnMsg": "Success"
}