Preparation Operations / Configuration of Trading Partners

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

Company’s Phone Number

FacsimileNumber String(30)

Company’s Facsimile Number

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)

RpHeader

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)

Transmission Message

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

Return Code

1: the request is successful.
Others: failed.

RtnMsg String(200)

Return Message

Example (JSON format)

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

Green World