Moksa1123 Taiwan Ecommerce Toolkit Taiwan Ecommerce Toolkit

Taiwan Logistics Development Skill

Comprehensive guide for Taiwan Logistics integration (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow + HCT direct API)

Supported Providers

This skill covers 6 logistics aggregators + 1 direct carrier API:

註：選用 HCT 直連 API 適合大量出貨企業；一般電商透過 aggregator (LogisticsType=HCT) 走 HCT 配送即可，不需自行串接。

Quick Reference

Core Concepts

Logistics Types:

• B2C (大宗寄倉): Bulk warehouse shipping - Merchant ships to logistics center, then distributed to stores
• C2C (店到店): Store-to-store - Merchant ships to convenience store, then delivered to pickup store

Trade Types:

• 取貨付款 (Cash on Delivery): Customer pays when picking up
• 取貨不付款 (No Payment): Customer only picks up (payment already completed)

Supported Convenience Stores:

1. 7-ELEVEN
2. FamilyMart (全家)
3. Hi-Life (萊爾富)
4. OK Mart

Key APIs:

1. Store Map Query - Select pickup/sender store
2. Create Shipment - Create logistics order
3. Get Shipment Number - Get shipping code
4. Print Label - Print shipping label
5. Query Shipment - Check order status
6. Modify Shipment - Update order details
7. Track Shipment - Track delivery history
8. Status Notification - Real-time status updates

Service Providers

NewebPay Logistics (藍新物流)

Encryption: AES-256-CBC + SHA256 (same as NewebPay payment)

API Style: Form POST with AES encryption

Supported Services:

• C2C Store-to-Store: 4 convenience stores (7-11, FamilyMart, Hi-Life, OK Mart)
• B2C Bulk Warehouse: 7-ELEVEN only

Test Environment:

• Store Map: https://ccore.newebpay.com/API/Logistic/storeMap
• Create Shipment: https://ccore.newebpay.com/API/Logistic/createShipment
• Get Shipment No: https://ccore.newebpay.com/API/Logistic/getShipmentNo
• Print Label: https://ccore.newebpay.com/API/Logistic/printLabel
• Query Shipment: https://ccore.newebpay.com/API/Logistic/queryShipment
• Modify Shipment: https://ccore.newebpay.com/API/Logistic/modifyShipment
• Track Shipment: https://ccore.newebpay.com/API/Logistic/trace

Production Environment:

• Replace ccore.newebpay.com with core.newebpay.com

ECPay Logistics (綠界物流)

Encryption: MD5 CheckMacValue

API Style: Form POST with URL-encoded parameters

Supported Services:

• C2C Store-to-Store: 4 convenience stores (7-11, FamilyMart, Hi-Life, OK Mart)
• C2C Frozen: 7-ELEVEN frozen goods
• Home Delivery: T-Cat, HCT, Pelican Express

Test Environment:

• Base URL: https://logistics-stage.ecpay.com.tw
• Create: POST /Express/Create
• Query: POST /Helper/QueryLogisticsTradeInfo/V2
• Print: POST /helper/printTradeDocument
• Map: POST /Express/map

Production Environment:

• Base URL: https://logistics.ecpay.com.tw

Logistics SubTypes (CVS):

• FAMI - FamilyMart (全家)
• UNIMART - 7-ELEVEN (常溫)
• UNIMARTFREEZE - 7-ELEVEN (冷凍)
• HILIFE - Hi-Life (萊爾富)
• OKMART - OK Mart

Logistics SubTypes (Home Delivery):

• TCAT - T-Cat (黑貓宅急便)
• ECAN - HCT (新竹物流)
• POST - Pelican Express (宅配通)

Temperature Control (Home Delivery):

• 0001 - Normal temperature (常溫)
• 0002 - Refrigerated (冷藏)
• 0003 - Frozen (冷凍)

Specification (Package Size):

• 0001 - 60cm
• 0002 - 90cm
• 0003 - 120cm
• 0004 - 150cm

Distance (Delivery Range):

• 00 - Same district
• 01 - Same city
• 02 - Cross city
• 03 - Outlying islands

Test Credentials:

• MerchantID: 2000132
• HashKey: 5294y06JbISpM5x9
• HashIV: v77hoKGq4kWxNNIS

PAYUNi Logistics (統一物流)

Encryption: AES-256-GCM + SHA256 (same as PAYUNi payment)

API Style: RESTful JSON with AES-GCM encryption

Supported Services:

• C2C Store-to-Store: 7-ELEVEN (normal temperature + frozen)
• B2C Bulk Warehouse: 7-ELEVEN only
• Home Delivery: T-Cat (normal temperature, frozen, refrigerated)

Test Environment:

• Base URL: https://sandbox-api.payuni.com.tw/api/
• Create Shipment: POST /logistics/create
• Query Shipment: POST /logistics/query
• Cancel Shipment: POST /logistics/cancel

Production Environment:

• Base URL: https://api.payuni.com.tw/api/

Logistics Types:

• PAYUNi_Logistic_711 - 7-11 C2C (normal temperature)
• PAYUNi_Logistic_711_Freeze - 7-11 C2C (frozen)
• PAYUNi_Logistic_711_B2C - 7-11 B2C (bulk warehouse)
• PAYUNi_Logistic_Tcat - T-Cat home delivery (normal)
• PAYUNi_Logistic_Tcat_Freeze - T-Cat frozen
• PAYUNi_Logistic_Tcat_Cold - T-Cat refrigerated

Temperature Codes:

• 1 - Normal temperature
• 2 - Frozen
• 3 - Refrigerated (T-Cat only)

Size & Weight Limits:

• Normal temperature: 150cm material volume, 20kg
• Frozen/Refrigerated: 120cm material volume, 15kg
• Material volume calculation: Length + Width + Height ≤ Limit

Transaction Flows

1. B2C Bulk Warehouse - Cash on Delivery

1. Create Order: Customer selects store, merchant calls Create Shipment API
2. Get Shipping Code: Merchant calls Get Shipment Number API & Print Label API
3. Merchant Ships: Merchant delivers goods to logistics center
4. Logistics Distributes: Logistics center verifies and distributes to pickup store
5. Customer Picks Up: Customer picks up and pays, NewebPay notifies merchant

2. C2C Store-to-Store - Cash on Delivery

1. Create Order: Customer selects store, merchant calls Create Shipment API
2. Get Shipping Code: Merchant calls Get Shipment Number API & Print Label API
3. Merchant Ships: Merchant delivers goods to sender store
4. Store Ships: Sender store ships to logistics center, then to pickup store
5. Customer Picks Up: Customer picks up and pays, NewebPay notifies merchant

3. B2C Bulk Warehouse - No Payment

1. Create Order: Customer selects store (payment already completed)
2. Get Shipping Code: Merchant calls Get Shipment Number API & Print Label API
3. Merchant Ships: Merchant delivers goods to logistics center
4. Logistics Distributes: Logistics center verifies and distributes to pickup store
5. Customer Picks Up: Customer picks up, NewebPay notifies merchant

4. C2C Store-to-Store - No Payment

1. Create Order: Customer selects store (payment already completed)
2. Get Shipping Code: Merchant calls Get Shipment Number API & Print Label API
3. Merchant Ships: Merchant delivers goods to sender store
4. Store Ships: Sender store ships to logistics center, then to pickup store
5. Customer Picks Up: Customer picks up, NewebPay notifies merchant

API Operations

1. Store Map Query API [NPA-B51]

Query convenience store locations for pickup or sender.

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/storeMap
• Production: https://core.newebpay.com/API/Logistic/storeMap

Request Parameters:

EncryptData_ Parameters:

Response EncryptData_ Parameters:

2. Create Shipment API [NPA-B52]

Create logistics shipment order after payment order is established.

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/createShipment
• Production: https://core.newebpay.com/API/Logistic/createShipment

EncryptData_ Parameters:

Response EncryptData_ Parameters:

3. Get Shipment Number API [NPA-B53]

Get shipping code before shipment. Merchants can print labels at convenience store Kiosk.

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/getShipmentNo
• Production: https://core.newebpay.com/API/Logistic/getShipmentNo

EncryptData_ Parameters:

Response EncryptData_ Parameters:

4. Print Label API [NPA-B54]

Print shipping labels to attach to products.

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/printLabel
• Production: https://core.newebpay.com/API/Logistic/printLabel

Important: Must use Form POST method (not JSON API call)

EncryptData_ Parameters:

Response: Returns HTML page with printable shipping label

5. Query Shipment API [NPA-B55]

Query logistics order information and status.

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/queryShipment
• Production: https://core.newebpay.com/API/Logistic/queryShipment

EncryptData_ Parameters:

Response EncryptData_ Parameters:

6. Modify Shipment API [NPA-B56]

Modify shipment order details (only for orders not yet shipped or expired).

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/modifyShipment
• Production: https://core.newebpay.com/API/Logistic/modifyShipment

Modifiable Conditions:

• Not yet obtained shipping number
• Shipment expired
• Store reselection

EncryptData_ Parameters:

Response EncryptData_ Parameters:

7. Track Shipment API [NPA-B57]

Track complete logistics delivery history.

Endpoint:

• Test: https://ccore.newebpay.com/API/Logistic/trace
• Production: https://core.newebpay.com/API/Logistic/trace

EncryptData_ Parameters:

Response EncryptData_ Parameters:

8. Status Notification [NPA-B58]

Real-time notification when shipment status changes.

Merchant provides NotifyURL to receive notifications

POST Parameters:

EncryptData_ Parameters:

Encryption Methods

Hash Data Processing

NewebPay Logistics uses the same encryption method as NewebPay Payment:

1. AES-256-CBC Encryption: Encrypt data using merchant's HashKey and HashIV
2. SHA256 Hash: Add HashKey + AES result + HashIV, then SHA256 hash and uppercase

Process:

EncryptData = AES-256-CBC(data, HashKey, HashIV)
HashData = SHA256(HashKey + EncryptData + HashIV).toUpperCase()

Status Codes

RetId Status Codes & RetString Descriptions

Error Codes

Common Error Codes

Important Notes

Amount Limits

• COD (Cash on Delivery): Maximum 20,000 NTD
• No Payment: Maximum 20,000 NTD

Batch Limits

• Get Shipment Number: Maximum 10 orders per request
• Print Label:
  • 7-ELEVEN: Maximum 18 labels
  • FamilyMart: Maximum 8 labels
  • Hi-Life: Maximum 18 labels
  • OK Mart: Maximum 18 labels

Store Code Notes

• For FamilyMart and OK Mart, the store code displayed on the map may not be the real code
• Always use the store code returned in the API response (StoreID field)

Timestamp

• Must use Unix timestamp (seconds since 1970-01-01 00:00:00 GMT)
• Tolerance: 120 seconds
• Incorrect timestamp will cause transaction failure

PAYUNi API Operations

1. Create 7-11 C2C Shipment

Create store-to-store logistics order.

Endpoint: POST /api/logistics/create

Request Body:

EncryptInfo Parameters:

Response (Decrypted EncryptInfo):

2. Create T-Cat Home Delivery

Create home delivery shipment.

Endpoint: POST /api/logistics/create

Additional EncryptInfo Parameters:

Delivery Time Slots:

• 01 - Before 13:00
• 02 - 14:00 - 18:00
• 03 - Not specified

Response (Decrypted EncryptInfo):

3. Query Shipment Status

Query logistics order status.

Endpoint: POST /api/logistics/query

EncryptInfo Parameters:

Response (Decrypted EncryptInfo):

Logistics Status Codes:

4. Status Notification Callback

Handle real-time status updates from PAYUNi.

Callback Request (POST to NotifyURL):

Decrypted EncryptInfo:

Response Required:

• Success: SUCCESS
• Error: Any other response

PAYUNi Encryption (AES-256-GCM)

Encryption Process

1. Create Query String from parameters
2. AES-256-GCM encrypt (with 16-byte tag)
3. Convert to hex: EncryptInfo = hex(encrypted + tag)
4. Generate HashInfo: SHA256(EncryptInfo + HashKey + HashIV)

Decryption Process

1. Convert hex to binary
2. Split: encrypted = data[:-16], tag = data[-16:]
3. AES-256-GCM decrypt and verify tag
4. Parse query string to get parameters

Best Practices

1. Store Selection: Always use the StoreID from the Store Map API response, not the displayed code
2. Error Handling: Implement proper error handling for all API calls with retry logic
3. Status Tracking: Use Status Notification webhook for real-time updates instead of polling
4. Encryption: Securely store HashKey and HashIV, never expose in client-side code
5. Order Numbers: Ensure MerchantOrderNo is unique across all orders
6. Timestamp: Always generate fresh timestamp for each API call
7. Testing: Use test environment extensively before going to production
8. Validation: Validate all user input (name, phone, email) before API calls
9. Logging: Log all API requests and responses for debugging and auditing
10. Notification URL: Ensure NotifyURL is accessible from NewebPay servers (not localhost)

Use Cases

E-commerce Platform

• Integrate store map for customers to select pickup location
• Create shipment automatically after order confirmation
• Send tracking updates to customers via email/SMS
• Handle returns and exchanges through modify shipment API

Marketplace

• Support multiple vendors shipping to convenience stores
• Provide unified logistics tracking interface
• Automate shipment number retrieval and label printing
• Handle COD payment collection and settlement

Subscription Service

• Schedule recurring shipments to same pickup store
• Automatic label generation for regular deliveries
• Batch shipment creation for multiple orders
• Track delivery success rate and optimize logistics

Related Resources

• EXAMPLES.md - Complete code examples (TypeScript, Python, PHP)
• references/NEWEBPAY_LOGISTICS_REFERENCE.md - NewebPay Logistics API full specification
• scripts/search.py - BM25 search engine for error codes and fields
• scripts/test_logistics.py - Connection testing tool

Support

NewebPay Technical Support

• Phone: 02-2655-8938
• Official Documentation: https://www.newebpay.com

API Version

Current Version: 1.0

Last Updated

2026-01-29

Total Lines: 750+

Source: Moksa1123/taiwan-ecommerce-toolkit — distributed by TomeVault.