PHPackages                             carllee1983/newebpay-logistics - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. carllee1983/newebpay-logistics

ActiveLibrary[API Development](/categories/api)

carllee1983/newebpay-logistics
==============================

NewebPay Logistics Integration PHP SDK. Supports various logistics methods including CVS pickup, home delivery, and more.

v2.3.0(6mo ago)0163↓93.3%MITPHPPHP ^8.1CI passing

Since Nov 28Pushed 6mo agoCompare

[ Source](https://github.com/CarlLee1983/newebpay-logistics)[ Packagist](https://packagist.org/packages/carllee1983/newebpay-logistics)[ Docs](https://github.com/CarlLee1983/newebpay-logistics)[ RSS](/packages/carllee1983-newebpay-logistics/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (10)Versions (9)Used By (0)

NewebPay Logistics Integration PHP SDK
======================================

[](#newebpay-logistics-integration-php-sdk)

[繁體中文](README_TW.md) | [English](README.md)

[![Latest Version on Packagist](https://camo.githubusercontent.com/40ef78f4f69b33629765b32d54732b2dc20ab8351dd7d37befa85eaf222d9ca1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6361726c6c6565313938332f6e657765627061792d6c6f676973746963732e737667)](https://packagist.org/packages/carllee1983/newebpay-logistics)[![Run Tests](https://github.com/CarlLee1983/newebpay-logistics/actions/workflows/run-tests.yml/badge.svg)](https://github.com/CarlLee1983/newebpay-logistics/actions/workflows/run-tests.yml)[![Software License](https://camo.githubusercontent.com/074b89bca64d3edc93a1db6c7e3b1636b874540ba91d66367c0e5e354c56d0ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e737667)](LICENSE.md)[![PHP Version](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565)](https://packagist.org/packages/carllee1983/newebpay-logistics)

A PHP SDK for integrating with the NewebPay Logistics API (藍新金流物流 API). This package simplifies the process of creating transactions, selecting stores (CVS), querying orders, and printing shipping labels.

Features
--------

[](#features)

- **Easy Integration**: Simple and intuitive API for common logistics operations.
- **Framework Agnostic**: Works with any PHP project (bundled with Laravel support).
- **Type Safety**: Utilizes PHP encapsulation to ensure data validity.
- **Frontend Friendly**: Built-in support for generating HTML forms for frontend frameworks (Vue, React, etc.).

Requirements
------------

[](#requirements)

- PHP ^8.1
- `ext-json` extension
- `ext-openssl` extension

Installation
------------

[](#installation)

Install via Composer:

```
composer require carllee1983/newebpay-logistics
```

Configuration
-------------

[](#configuration)

Initialize the library with your NewebPay Logistics credentials.

```
use CarlLee\NewebPayLogistics\NewebPayLogistics;

$merchantId = 'YOUR_MERCHANT_ID';
$hashKey = 'YOUR_HASH_KEY';
$hashIV = 'YOUR_HASH_IV';

// The last argument is optional for server URL override (defaults to testing env)
$logistics = NewebPayLogistics::create($merchantId, $hashKey, $hashIV);
```

### Parameters

[](#parameters)

ParameterApplicationDescription`$merchantId`**Required**Your Shop ID (商店代號) provided by NewebPay.`$hashKey`**Required**Hash Key (HashKey) for encryption.`$hashIV`**Required**Hash IV (HashIV) for encryption.`$serverUrl`OptionalAPI Base URL. Default is testing env: `https://ccore.newebpay.com/API/Logistic`.Laravel Integration
-------------------

[](#laravel-integration)

This package includes a Service Provider and Facade for seamless Laravel integration.

### 1. Installation

[](#1-installation)

Publish the configuration file:

```
php artisan vendor:publish --tag=newebpay-logistics-config
```

### 2. Configuration

[](#2-configuration)

Add the following variables to your `.env` file:

```
NEWEBPAY_LOGISTICS_MERCHANT_ID=your_merchant_id
NEWEBPAY_LOGISTICS_HASH_KEY=your_hash_key
NEWEBPAY_LOGISTICS_HASH_IV=your_hash_iv
# Optional: Override server URL (default is testing environment)
# NEWEBPAY_LOGISTICS_SERVER_URL=https://core.newebpay.com/API/Logistic
```

### 3. Usage via Facade

[](#3-usage-via-facade)

You can use the `NewebPayLogistics` facade anywhere in your Laravel application.

```
use NewebPayLogistics;
use CarlLee\NewebPayLogistics\Parameter\ShipType;

public function map()
{
    $map = NewebPayLogistics::map();
    $map->setShipType(ShipType::SEVEN_ELEVEN);
    // ...

    return NewebPayLogistics::generateForm($map);
}
```

Usage
-----

[](#usage)

### 1. Map Interface (電子地圖)

[](#1-map-interface-電子地圖)

Redirect the user to the logistics provider's map interface to select a store (7-11, FamilyMart, etc.).

```
use CarlLee\NewebPayLogistics\Parameter\LgsType;
use CarlLee\NewebPayLogistics\Parameter\ShipType;

$map = $logistics->map();
$map->setMerchantTradeNo('TRADE' . time());
$map->setLgsType(LgsType::B2C);
$map->setShipType(ShipType::SEVEN_ELEVEN);
$map->setIsCollection('N'); // N: No collection, Y: Collection
$map->setServerReplyURL('https://example.com/reply');

// Generate auto-submit HTML form
echo $logistics->generateForm($map);
```

#### 1-1. Frontend Integration (Vue/React)

[](#1-1-frontend-integration-vuereact)

If you are using a decoupled architecture, return the form data as JSON.

```
$formBuilder = $logistics->getFormBuilder();
$data = $formBuilder->getFormData($map);

echo json_encode($data);
// Output: {"url": "...", "method": "post", "params": { ... }}
```

### 2. Create Order (建立物流訂單)

[](#2-create-order-建立物流訂單)

Create a logistics order for B2C or C2C transactions.

```
use CarlLee\NewebPayLogistics\Parameter\LgsType;
use CarlLee\NewebPayLogistics\Parameter\ShipType;
use CarlLee\NewebPayLogistics\Parameter\TradeType;

$create = $logistics->createOrder();
$create->setMerchantTradeNo('TRADE' . time());
$create->setLgsType(LgsType::B2C);
$create->setShipType(ShipType::SEVEN_ELEVEN);
$create->setTradeType(TradeType::PAYMENT);
$create->setReceiverName('John Doe');
$create->setReceiverCellPhone('0912345678');
// ... more parameters

// This API usually responds with a redirect or direct result depending on the content
// But strictly speaking, Create Order in some NewebPay flows is also a form post redirect.
// Check official docs for specific flow.
```

### 3. Query Order (查詢物流訂單)

[](#3-query-order-查詢物流訂單)

Query the status of an existing order.

```
$query = $logistics->query();
$query->setLogisticsID('LOGISTICS_ID');
$query->setMerchantTradeNo('TRADE_NO');

// This is a direct API call
$response = $logistics->send($query);

if ($response->isSuccess()) {
    echo "Status: " . $response->getMessage();
}
```

Examples
--------

[](#examples)

Check the `examples/` directory for complete vanilla PHP scripts:

- [Map Operation](examples/example_map.php)
- [Create Order](examples/example_create_order.php)
- [Query Order](examples/example_query_order.php)
- [Print Order](examples/example_print_order.php)
- [Laravel Integration](examples/laravel_example.php)

API Reference
-------------

[](#api-reference)

For detailed API documentation, please refer to the files in the `doc/` directory:

- [English API Reference](doc/api_reference_en.md)
- [Traditional Chinese API Reference](doc/api_reference_tw.md)

FAQ
---

[](#faq)

**Q: How do I change the environment to Production?**A: By default, `NewebPayLogistics::create()` uses the testing URL. Pass the production URL as the 4th argument, or set `NEWEBPAY_LOGISTICS_SERVER_URL` in Laravel `.env`.

**Q: Can I use this without Laravel?**A: Yes! The package is framework-agnostic. See the [Configuration](#configuration) section.

**Q: I get a "Validation Validation" error.**A: Ensure all required fields are set. The SDK validates the request parameters before generating the payload.

**Q: I get a "Check Value Error" or Decryption failure.**A: This usually means your Merchant ID, Hash Key, or Hash IV are incorrect. Please double check them. Also ensure there are no extra spaces in your keys. In some cases, ensure your input data doesn't contain encoded characters that might mess up the length calculation.

Development
-----------

[](#development)

```
# Run tests
composer test

# Check code style
composer check

# Fix code style
composer format
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

License
-------

[](#license)

MIT

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance66

Regular maintenance activity

Popularity11

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 80% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

6

Last Release

209d ago

Major Versions

v1.x-dev → v2.0.02025-11-28

PHP version history (3 changes)v1.0.0PHP ^7.4

v2.0.0PHP ^8.3

v2.3.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/6cc3f5bb28af8b207b65843e86f3b3e9feb1efd05b8ba888e1fa223a370ab822?d=identicon)[Carl Lee](/maintainers/Carl%20Lee)

---

Top Contributors

[![CarlLee1983](https://avatars.githubusercontent.com/u/8252510?v=4)](https://github.com/CarlLee1983 "CarlLee1983 (12 commits)")[![google-labs-jules[bot]](https://avatars.githubusercontent.com/in/842251?v=4)](https://github.com/google-labs-jules[bot] "google-labs-jules[bot] (2 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

laravelsdkcvsshippingTaiwanlogisticsnewebpayconvenience-store

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/carllee1983-newebpay-logistics/health.svg)

```
[![Health](https://phpackages.com/badges/carllee1983-newebpay-logistics/health.svg)](https://phpackages.com/packages/carllee1983-newebpay-logistics)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.1k](/packages/laravel-framework)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.5M7](/packages/avalara-avataxclient)[keboola/storage-api-client

Keboola Storage API PHP Client

10405.9k40](/packages/keboola-storage-api-client)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

273.0k](/packages/eslazarev-wildberries-sdk)[bushlanov-dev/max-bot-api-client-php

Max Bot API Client library

486.3k](/packages/bushlanov-dev-max-bot-api-client-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)