Scenario
This B2B e-invoice API document mainly has two modes: Exchange and Certification.
Merchants have to request this API to configure or set the trading partnets (i.e. to set the buyer or seller) and to set which mode is going to be used.
API URL
- Stage：https://einvoice-stage.ecpay.com.tw/B2BInvoice/MaintainMerchantCustomerData
- Production：https://einvoice.ecpay.com.tw/B2BInvoice/MaintainMerchantCustomerData
HTTPS Transfer Protocol
- Content Type ：application/json
- HTTP Method ：POST
Merchant’s request(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 String(10)
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": 1234567890
},
"Data": "enter your data"
}
Message payload of Data(Json format) : please urlencode the JSON string firstly and then do AES encryption
MerchantID String(10)
Required
Action String(10)
Required
Possible value:
- Add
- Update
- Delete
CustomerNumber String(20)
Company’s Number
- Can be the same as Identifier
Identifier String(8)
Required
Company’s tax ID in Taiwan
- The value is a fixed serial number of 8-digit, which could not be changed after setting
type String(1)
Required
Transaction Target
- 1: Buyer
- 2: Seller
- 3: Buyer & Seller
CompanyName String(60)
Required
Company’s Name
PersonInCharge String(30)
The person in charge of the company
Address String(100)
Company’s Address
TelephoneNumber String(30)
TradingSlang String(20)
Required
Trading Code
ExchangeMode String(1)
Required
Exchange Mode
- 0: Certification
- 1: Exchange
Certification: ECPay will upload your invoice to the Platform of Ministry of Finance and will only be used to output invoices
Special Notes :
- ECPay cannot receive e-invoice from other business entities.
- Please make sure to go to the Platform of Ministry of Finance firstly to set up the reception by ECPay.
EmailAddress String(80)
Required
Company’s Email
- This field can be populated with more than one e-mail address.
- Please separate each e-mail address by semicolon.
SalesName String(30)
Contact person
ContactAddress String(100)
Contact Address
Example(Json Format)
{
"MerchantID": "2000132",
"Action": "Add",
"Identifier": "53538851",
"type": "2",
"CompanyName": "EcPay"
"Address": " No.3, Da Wang Road, Neihu District, Taipei ",
"TelephoneNumber": "22222222",
"TradingSlang": "123",
"ExchangeMode": "1",
"EmailAddress": "abc@pay.com.tw; def@pay.com.tw ; ghi@pay.com.tw"
}
ECPay response (JSON format)
PlatformID String(10)
- Platform merchant ID
MerchantID String(10)
Response Header
Timestamp String(10)
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.
TransCode Int
- 1: data (MerchantID, RqHeader, and Data) is successfully accepted by ECPay.
- Others: failed.
TransMsg String(200)
Data String
Data responded.
- This is the encrypted data in JSON format.
AES Encryption Description
ECPay response example (JSON format)
{
"MerchantID": "3002607",
"RpHeader": {
"Timestamp": 1234564848
},
"TransCode": 1,
"TransMsg": "Success",
"Data": "…"
}
Parameter description in Data (JSON format)
RtnCode Int
- 1: the request is successful.
- Others: failed.
RtnMsg String(200)
Return Message
Example (JSON format)
{
"RtnCode": 1,
"RtnMsg": "Success"
}