Logistics API Document​

Creating orders(B2C/C2C) / Create store logistics order(B2C/C2C)

Introduction

Once the customer has created an order from merchant, then merchant can use POST method, pass the shipping information (includes selected store electronic map data, etc.) to ECPAY and proceed to create store orders.

❗  Special Note：

  1. (Family Mart or 7-ELEVEN) B2C bulk deposit shipments must first complete the “shipping label test“. If the shipping label check fails, shipments will be returned by the logistics center. The cost will be merchant’s responsibility.
  2. For the shipping label check process, please refer to merchant management backend-> logistics->and query for-> trade document.
  3. The testing environment should be conducted using the following stores, 7-ELEVEN: 131386, 7-ELEVEN registration pickup store: 896539, FamilyMart: 006598, OKMart: 1328.
  4. The time between selecting the map and creating an order at the store is too long, and it is necessary to note that the store is closed or the store is changed so that the order cannot be created.
  5. After the order is generated, please check whether you received the successful logistics status (ServerReplyURL) to ensure that you will be notified of the logistics status continuously.
  6. (B2C) Please use the Logistics Order Inquiry API to get the ShipmentNo.
  7. When creating an order, there is a limit on the amount of goods according to the logistics subtype.
  8. If your account balance is too low, you will not be able to create a logistics order. It is recommended to keep a certain amount of money in your ECPAY account or pre-deposit your ECPAY account balance to the Merchant’s backend for logistics fee deduction.
  9. For other shipping information, please refer to Appendix 5. Shipping Notes.

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)

Merchant transaction number
  • 1. The Merchant transaction number is unique and cannot be reused (alphanumerical string).
  • 2. 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.
CVS: Convenience store pickup

LogisticsSubType String(20)
Required

Logistics subtype.
B2C

  • FAMI: Family Mart
  • UNIMART: 7-ELEVEN
  • HILIFE: Hi-Life
  • UNIMARTFREEZE: refrigeration transportation of 7-ELEVEN

C2C

  • FAMIC2C: Family Mart store to store
  • UNIMARTC2C: 7-ELEVEN store to store
  • HILIFEC2C: Hi-Life store to store
  • OKMARTC2C:OK store to store

❗ Special Note：

  1. If the application type is B2C, only FAMI, UNIMART, HILIFE, UNIMARTFREEZE can be used.
  2. If the application type is C2C, only FAMIC2C, UNIMARTC2C, HILIFEC2C, OKMARTC2C can be used.

GoodsAmount Int
Required

Goods price value.
  • The price amount of goods ranges from $1 to $20,000 NTD.
  • If the total goods value amount exceeds the price range, order creation will fail and return error code 10500040 (Goods value amount error).

CollectionAmount Int

Amount of money to be collected. When logistics subtype is UNIMARTC2C (7-ELEVEN C2C), the collection amount must be the same as the goods value amount.

IsCollection String(1)

Collect payment or not.
  • N: The default value is set to “No payment collection“.
  • Y: If payment is collected, the amount of the payment collected shall be the goods value

GoodsName String(50)

Goods name
B2C

  • FAMI: Family Mart (may be left empty)
  • UNIMART: 7-ELEVEN (may be left empty)
  • HILIFE: Hi-Life (may be left empty)

C2C

  • FAMIC2C: Family Mart store to store (may be left empty)
  • UNIMARTC2C: 7-ELEVEN store to store (may NOT be left empty)
  • HILIFEC2C: Hi-Life (may NOT be left empty)
  • OKMARTC2C:OK store to store (may NOT be left empty)

❗ Special Note：

  • Characters including ^ ‘ ` ! @ # % & * + \ ” < > | _ [ ] and other special symbols are not allowed.
  • Prioritize checking for special characters, then verify if the length exceeds the limit.
  • Length limit checking rule:
    Chinese characters count as 2 bytes, full-width characters count as 2 bytes, and all others count as 1 byte.

SenderName String(10)
Required

Sender name

❗ Special Note：

  • The character limit is 4~10 characters (Chinese 2~5 characters, English 4~10 characters).
  • Chinese and English characters only, numbers, special symbols and spaces are not allowed.
  • All unclaimed C2C store to store shipments will be returned to the originating store, and will require an I.D. card to pick up. Please do not use company name as the sender name to avoid any problems claiming returned deliveries.

SenderPhone String(20)

SenderCellPhone String(10)

Sender’s mobile phone number. If LogisticsSubType = UNIMARTC2C (7-ELEVEN store to store) or HILIFEC2C (Hi-Life store to store), OKMARTC2C(OK store to store) SenderCellPhone cannot be left empty.

❗ Special Note：

  • Only a 10-digit numeric string beginning with 09 is allowed.
  • If LogisticsSubType = FAMIC2C and if SenderCellPhone is empty, please login Admin panel to enter a cell phone number (otherwise the sender will not receive SMS notification).

ReceiverName String(10)
Required

Recipient’s name

❗ Special Note：

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

ReceiverPhone String(20)

Recipient’s phone number

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

ReceiverCellPhone String(10)
Required

Recipient phone

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

ReceiverEmail String(50)

Recipient’s email

TradeDesc String(200)

Transaction description

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)

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, Please refer to the appendix for more information on checksum mechanism.

ReceiverStoreID String(6)
Required

Receiver’s store ID

ReturnStoreID String(6)

Return store ID. If no ReturnStoreID is set, the goods will be returned to the original shipping store. If set, it will be sent to the designated return store.

❗ Special Note：7-11 C2C only, Other C2C with this parameter will still be returned to the original shipping store.

Response Parameter Description

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. Please refer to the logistics status code list.

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.
Merchant must verify this field. Please refer to Checksum

Response Messages Sample

  • 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