Logistics API Document​

Home Delivery / Creating Shipment Orders (Home Delivery)

Introduction

Once the customer has created an order from merchant, then merchant can use POST method, pass the shipping information to ECPay and proceed to shipping.

❗  Special Note：

  1.  When creating a logistics order, please check if the ServerReplyURL also receives logistics status successfully so that it can ensure the server can receive follow-up notification.
  2.  When using Post home delivery service, after creating an order, please confirm the order logistics status as “Post has confirmed the information” before delivering the parcel to the Post office.

API URLs

  • Stage：https://logistics-stage.ecpay.com.tw/Express/Create
  • Production：https://logistics.ecpay.com.tw/Express/Create

HTTPS Transfer Protocol

  • Accept：text/html
  • Content Type：application/x-www-form-urlencoded
  • HTTP Method：POST

Request Parameter Description

MerchantID String(10)
Required

Provided by ECPAY

MerchantTradeNo String(20)

logistics order number.
  • The Merchant transaction number is unique and cannot be reused (alphanumerical string).
  • The Merchant transaction number can be left empty and the system will automatically generate a new order number.

MerchantTradeDate String(20)
Required

  • Please set the time according to the moment of the transaction when the consumer places the order.
    (This time will not be equal to the time when ECPay complete the logistics order.)
  • Format should be: yyyy/MM/dd HH:mm:ss

LogisticsType String(20)
Required

Logistics type
  • HOME: Home Delivery

LogisticsSubType String(20)
Required

Logistics subtype
  • TCAT: TCAT Home Delivery
  • POST: POST Home Delivery

GoodsAmount Int
Required

Goods name

  • Goods amount range is limited to $1 or more.

GoodsName String(50)

TCAT (may be left empty)

  • Characters including ^ ‘ ` ! @ # % & * + \ ” < > | _ [ ] and other special symbols are not allowed.
  • If the [LogisticsSubType] is TCAT, please do not use the fullwidth symbol.

GoodsWeight Number

  • If the [LogisticsSubType] is POST, this parameter must not be empty.
  • Upper limit 20kg, decimal 3 digits
  • Unit is kilogram

SenderName String(10)
Required

Sender name

❗ Special Note：

  1. The character limit is 4~10 characters (Chinese 2~5 characters, English 4~10 characters).
  2. Chinese and English characters only, numbers, special symbols and spaces are not allowed.

SenderPhone String(20)

Sender’s phone number

  • You must enter either home phone or mobile phone number, may not be left blank.

❗ Special Note：

  • 1.Numbers + special characters are allowed. Special character are limited to only ()-# .
  • 2. Only a 10-digit numeric string beginning with 09 is allowed.

SenderCellPhone String(20)

Sender’s mobile phone number.

  • You must enter either home phone or mobile phone number, may not be left blank.

❗ Special Note：Only a 10-digit numeric string beginning with 09 is allowed.

SenderZipCode String(6)
Required

Sender’s ZipCode

SenderAddress String(60)
Required

Sender’s Address

❗ Special Note：The character limit must be greater than 6 characters and must not exceed 60 characters.

ReceiverName String(10)
Required

Recipient’s name

❗ Special Note：

  1.  Character limit is 4-10 characters (Chinese 2-5 characters, English 4-10 characters).
  2.  Chinese and English characters only, numbers, special symbols and spaces are not allowed.

ReceiverPhone String(20)

Recipient’s phone number. You must enter either home phone or mobile phone number, may not be left blank.

❗ Special Note：Numbers + special characters are allowed. Special character are limited to only ()-# .

ReceiverCellPhone String(20)

Recipient phone

❗ Special Note：Only a 10-digit numeric string beginning with 09 is allowed.

ReceiverZipCode String(6)
Required

Recipient’s postal code

ReceiverAddress String(60)
Required

Recipient’s address

❗ Special Note：Must contain more than 6 characters but cannot exceed 60 characters.

ReceiverEmail String(50)

Recipient’s email

Temperature String(4)

Temperature
  • 0001: Normal temperature (default)
  • 0002: Refrigerated
  • 0003: Freezer

❗ Special Note：If the [LogisticsSubType] is POST, it only allows the use of 0001 normal temperature for Temperature setting.

Distance String(2)

Distance
  • 00: Same city/county (default)
  • 01: Other cities/counties
  • 02: Outlying island

❗ Special Note：

  • When the system checks that the ReceiverAddress and the SenderAddress do not match the value entered for Distance, the system will automatically correct the Distance to the correct value.
  • Please ignore this parameter if the [LogisticsSubType] is POST

Specification String(4)

Specification
  • 0001: 60cm (default)
  • 0002: 90cm
  • 0003: 120cm
  • 0004: 150cm

❗ Special Note：

  • When 0002:Refrigerated and 0003: freezer are chosen for temperature, the specification does not include the 0004:150cm option.
  • Please ignore this parameter if the [LogisticsSubType] is POST

ScheduledPickupTime String(1)

Scheduled pickup time period

  • The time when the home delivery logistics company is scheduled to pick up the goods
  • Currently, we do not provide a scheduled pickup time slot. Please set the parameter to 4 (indicating no specific time slot is required).

❗ Special Note：Please ignore this parameter if the [LogisticsSubType] is POST.

ScheduledDeliveryTime String(2)

Scheduled delivery time period. The following possible values refer to the home delivered goods that are scheduled to arrive
  • 1: Before 13:00
  • 2: 14:00 – 16:00
  • 3: 14~18
  • 4: No preference

❗ Special Note：Please ignore this parameter if the [LogisticsSubType] is POST.

TradeDesc String(200)

Transaction description

❗ Special Note：If the length exceeds 200, the excess will be cut off.

ServerReplyURL String(200)
Required

Server-side reply URL. Logistics status notifications will be sent via this URL.

ClientReplyURL String(200)

Client-side reply URL. When this parameter is not empty, page will be redirected to this URL once a logistic order has been created.

❗ Special Note：To limit order creations only through Server, do not fill in this parameter.

Remark String(200)

If LogisticsSubType = ECAN, the content to this field should not break line; the line which is broken will become empty and should not over 60 characters.

PlatformID String(10)

  • Provided by ECPAY, this parameter is used by Platform, regular Merchants please pass an empty value.
  • When being used by Platform, please use the associated MerchantID bound to Merchant.

CheckMacValue String
Required

Checksum.

綠界Response參數說明

MerchantID String(10)

MerchantTradeNo String(20)

Merchant transaction number.

  • The Merchant transaction number sent to ECPAY when an order is created.

RtnCode Int

Current logistics status.

RtnMsg String(200)

Logistics status description

AllPayLogisticsID String(20)

logistics order number.

  • Please keep the link relationship between ECPAY transaction number and AllPayLogisticsID.

LogisticsType String(20)

Logistics type

LogisticsSubType String(20)

Logistics subtype

GoodsAmount Int

Goods price value.

  • Compensation amount for lost goods, numbers only.

UpdateStatusDate String(20)

Logistics status update time.

  • Format is：yyyy/MM/dd HH:mm:ss

ReceiverName String (60)

Recipient’s name.

ReceiverPhone String(20)

Recipient’s phone number.

ReceiverCellPhone String(20)

Recipient phone.

  • Only a 10-digit numeric string beginning with 09 is allowed.

ReceiverEmail String(50)

Recipient’s email.

ReceiverAddress String(200)

Recipient’s address.

CVSPaymentNo String(15)

Shipping number.

CVSValidationNo String(10)

Verification code.

  • Return if the pickup convenience store is  7-ELEVEN store to store.

BookingNote String(50)

Consignment number.

  • When [LogsticsType] is set to “HOME“, may not be left empty.

CheckMacValue String

Checksum.

❗ Special Note：

  • After the order has been successfully generated, please check if the ServerReplyURL has received the successful logistics status to ensure that you continue to be notified of the logistics status.

Example response message from sever logistics order creation：

  • Correct：
				
					1|MerchantID=XXX&MerchantTradeNo=XXX&RtnCode=XXX&BookingNote=&RtnMsg=XXX&AllPayLogisticsID=XXX&LogisticsType=XXX&LogisticsSubType=XXX&GoodsAmount=XXX&UpdateStatusDate=XXX&ReceiverName=XXX&ReceiverPhone=XXX&ReceiverCellPhone=XXX&ReceiverEmail=XXX&ReceiverAddress=XXX&CVSPaymentNo=XXX &CVSValidationNo=XXX &CheckMacValue=XXX
  • Error：
				
					0| ErrorMessage

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

Green World