Notifications Operations / Issuing Notifications

Application Scenarios

Merchants can integrate this API to notify the customer when issuing e-invoice or allowance or any other scenarios. The notification can also be done by settings on ECPay’s dashboard if merchants do not want to integrate this API.

API URLs:

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

Special Notes :

In the satge environment, ECPay will not send any notification “actively”, nor will it send any notification by using the vendor’s backend “Supplemental Notification”.
If the notification option is enabled in [ Vendor Backend > Invoice Notification Method Setting ], there is no need to connect to this API unless there is a need for additional supplemental notifications to avoid duplicate notifications.
Since ECPay will check the winning invoice on 29th of every odd month (i.e. January, March, May, July, September, and November), merchants should set the e-mail address beforehand so that Green World can notify consumers if he/she wins the invoice lottery.

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

InvoiceNo String(10)
Required

E-Invoice number

AllowanceNo String(16)

Allowance Code

Special Notes : Required if InvoiceTag = A, AL or OA.

Phone String(20)

Delivery SMS number
This parameter can be chosen between the customer’s Email, if the customer’s Email is blank then this parameter needs value
Format is numerical digits

NotifyMail String(200)

Deliver EMAIL
Either [Phone] or [NotifyEmail] is required. I.e. if [Phone] is not sent, [NotifyMail] will be required.
Only valid email formats are accepted.
More than an email is allowed. To separate multiple email addresses please use the semicolon character (;).

Notify String(1)
Required

Delivery method
Possible values:
S: SMS
E: EMAIL
A: All methods

Special Notes : If InvoiceTag = OA, this value should be E only.

InvoiceTag String(2)
Required

Type of notification
Possible values:
I: notification of an e-invoice being created
II: notification of e-Invoice being invalidated
A: notification of allowance being created
AI: notification of allowance being cancelled
AW: notification of winning the e-Invoice lottery
OA: Online allowance cancellation agreement

Special Notes : OA is to send an e-mail consent agreement of cancelling allowance ticket to customer’s email.

Notified String(1)
Required

Delivery party
Possible values:
C: Deliver notification to customer
M: Deliver notification to merchant
A: Deliver both notifications

Special Notes :

If the delivery party (Notified) is A, make sure the settings of dashboard is enable to receive notifications.
If InvoiceTag = OA, this value should be C only.

Example

				
					{
  "MerchantID": 2000132,
  "InvoiceNo": "UV11100016",
  "AllowanceNo": "2019091719477262",
  "Phone": "0912345678",
  "NotifyMail": "test@ecpay.com.tw",
  "Notify": "E",
  "InvoiceTag": "I",
  "Notified": "A"
}

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.

MerchantID String(10)

Example

				
					{
  "RtnCode": 1,
  "RtnMsg": "Success",
  "MerchantID": 2000132
}

Green World