Logistics Information Upload

Use this API to upload logistics delivery information for transactions, enabling settlement confirmation and order tracking. The API accepts carrier codes and tracking numbers to complete the transaction confirmation process.

Use Cases

Upload logistics information for:

• stc pay Settlement: Required for stc pay transactions to trigger settlement processing
• Order Tracking: Link logistics data to transactions for merchant and customer package tracking
• Dispute Resolution: Provide shipping evidence for transaction disputes and chargeback defense

stc pay Payment Requirements

When using stc pay payment method, the following conditions must be met to upload logistics information and trigger settlement:

• Order Status: Transaction must be in final status (success or failure, not processing)
• Package Status: Must upload logistics information for signed/delivered packages only
• Transaction Type: Must be physical goods transaction (not digital goods or installment payments)
• Settlement Impact: Onerway will only process settlement after valid logistics information is uploaded

Other payment methods can optionally integrate this API for tracking and management purposes.

Upload Timing

Upload logistics information at these recommended times:

1. After Package Ships: Upload tracking number promptly for customer tracking
2. After Package Delivery (stc pay required): Upload immediately after customer signature to trigger settlement
3. Within 30 Days of Transaction: Upload within this timeframe to avoid reconciliation and settlement delays

Carrier Code List

Onerway supports over 1,000 logistics carriers worldwide. Due to the extensive list, we provide a downloadable csv file for your reference:

📥 Download Carrier Code List

The csv file contains:

• Carrier code (used in carrierNo parameter)
• Carrier name

Usage Recommendation

Download and save the carrier code list for reference during integration development and logistics information uploads.

API Request Parameters

POST

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
transactionId	String	20	Yes	Yes	Transaction ID generated by Onerway.
carrierNo	String	64	Yes	Yes	Carrier code identifying the logistics service provider. Download Carrier Code List
trackingNo	String	64	Yes	Yes	Logistics tracking number for package delivery tracking.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.

Response

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

Parameter	Type	Length	Required	Signed	Description
transactionId	String	20	Yes	Yes	Transaction ID generated by Onerway.

API Usage Examples

POST

Request

{
  "merchantNo": "800058",                    // Merchant number
  "transactionId": "1484408335541923840",    // Onerway transaction ID
  "carrierNo": "SF",                         // Carrier code (e.g., SF for SF Express)
  "trackingNo": "SF1234567890",              // Logistics tracking number
  "sign": "a1b2c3d4e5f6789..."               // Signature string
}

Response - Success

{
  "respCode": "20000",                       // Success response code
  "respMsg": "Success",                      // Response message
  "data": {
    "transactionId": "1484408335541923840"   // Transaction ID
  }
}

Response - Order Status Error

{
  "respCode": "40001",                       // Error response code
  "respMsg": "Transaction not in final status", // Order not in final status
  "data": null
}

Common Error Scenarios

Error Scenario	Solution
Order not in final status	Wait for transaction to complete (success or failure) before uploading
Transaction not found	Verify transactionId is correct
Invalid carrier code	Download and check Carrier Code List
Duplicate upload	Logistics information already recorded, no need to re-upload
Signature verification failed	Review signature generation logic, see Signature Guide

Implementation Best Practices

1. Order Status Validation: Check order completion status before upload to avoid status-related failures
2. Accurate Logistics Data: Ensure tracking numbers are correct for optimal customer tracking experience
3. Timely Upload: Upload logistics information promptly after shipment to improve customer satisfaction
4. Error Handling: Implement retry mechanisms for temporary errors like network failures
5. Logging: Maintain upload records and response results for troubleshooting
6. stc pay Special Requirements: For stc pay transactions, upload only after package delivery to enable settlement
7. Idempotency: Support duplicate uploads of same logistics information; system handles deduplication automatically

Merchant Integration Checklist

Before going live, verify:

• Obtained correct carrier code list
• Implemented order status checking logic
• Tested normal upload flow
• Tested error scenarios (order not found, status errors, etc.)
• Implemented error handling and retry mechanisms
• Added logging capabilities
• Verified delivery status checking for stc pay transactions
• Completed end-to-end testing in sandbox environment