PHPackages                             carllee/line-pay-core-v4 - 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. carllee/line-pay-core-v4

ActiveLibrary[API Development](/categories/api)

carllee/line-pay-core-v4
========================

Core library for LINE Pay API V4 SDK - Provides shared utilities, base client, types, and error handling for building LINE Pay integrations

v1.0.1(5mo ago)0271↓100%[2 PRs](https://github.com/CarlLee1983/line-pay-core-v4-php/pulls)2MITPHPPHP ^8.1CI passing

Since Dec 11Pushed 4mo agoCompare

[ Source](https://github.com/CarlLee1983/line-pay-core-v4-php)[ Packagist](https://packagist.org/packages/carllee/line-pay-core-v4)[ Docs](https://github.com/CarlLee1983/line-pay-core-v4-php)[ RSS](/packages/carllee-line-pay-core-v4/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (5)Used By (2)

LINE Pay Core V4 PHP
====================

[](#line-pay-core-v4-php)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/04744bae0a61d2ffe29c26f07a9612eae20445fc6feaeb77b3af1f0e9be6447c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e312d3838393242462e737667)](https://www.php.net/)

**Core library for LINE Pay API V4 SDK.**Provides shared utilities, base client, configuration, and error handling that power the Online and Offline SDKs.

**🌐 Language / 語言 / 言語 / ภาษา:**[English](./README.md) | [繁體中文](./README_ZH.md) | [日本語](./README_JA.md) | [ภาษาไทย](./README_TH.md)

Architecture
------------

[](#architecture)

 ```
graph TD
    subgraph "Your Application"
        A[Your Code]
    end

    subgraph "LINE Pay SDKs"
        B[line-pay-online-v4]
        C[line-pay-offline-v4]
    end

    subgraph "Core Layer"
        D[line-pay-core-v4]
        D1[LinePayBaseClient]
        D2[LinePayUtils]
        D3[Error Classes]
        D4[Configuration]
    end

    subgraph "LINE Pay API"
        E[LINE Pay Server]
    end

    A --> B
    A --> C
    B --> D
    C --> D
    D --> D1
    D --> D2
    D --> D3
    D --> D4
    D1 --> E

    style D fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333
    style C fill:#bbf,stroke:#333
```

      Loading Overview
--------

[](#overview)

This package is the **shared foundation** for building LINE Pay V4 integrations in PHP. It handles the "heavy lifting" so that the Online and Offline SDKs can focus on their specific API logic.

### Key Responsibilities

[](#key-responsibilities)

ComponentWhat It DoesWhy It Matters**HMAC-SHA256 Signature**Generates and verifies API signaturesThe most complex part of LINE Pay V4 API — one wrong byte and requests fail**HTTP Client Wrapper**Encapsulates Guzzle with retry logicHandles timeouts, connection errors, and response parsing consistently**Unified Error Parsing**Parses LINE Pay error codes into typed exceptions`1xxx` = Auth, `2xxx` = Payment, `9xxx` = Internal — no more guessing**Configuration Management**Type-safe config with environment supportPrevents "oops, wrong credentials in production" mistakesRequirements
------------

[](#requirements)

- PHP 8.1 or higher
- ext-json
- ext-openssl
- Guzzle HTTP Client 7.0+

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

[](#installation)

```
composer require carllee/line-pay-core-v4
```

> ⚠️ **Note:** This is a **core library** meant to be used as a dependency.
>
> **Most developers should use the ready-made SDKs instead:**
>
> - For online payments (web/app checkout): [`carllee/line-pay-online-v4`](https://github.com/CarlLee1983/line-pay-online-v4-php)
> - For offline payments (POS/Kiosk): [`carllee/line-pay-offline-v4`](https://github.com/CarlLee1983/line-pay-offline-v4-php)
>
> **Use this package directly only if** you need to build a custom LINE Pay client with specialized behavior.

Usage
-----

[](#usage)

### Creating a Custom Client

[](#creating-a-custom-client)

```
use LinePay\Core\LinePayBaseClient;
use LinePay\Core\Config\LinePayConfig;

class MyLinePayClient extends LinePayBaseClient
{
    public function requestPayment(array $body): array
    {
        return $this->sendRequest('POST', '/v3/payments/request', $body);
    }

    public function confirmPayment(string $transactionId, array $body): array
    {
        return $this->sendRequest(
            'POST',
            "/v3/payments/{$transactionId}/confirm",
            $body
        );
    }
}

// Usage
$config = new LinePayConfig(
    channelId: getenv('LINE_PAY_CHANNEL_ID'),
    channelSecret: getenv('LINE_PAY_CHANNEL_SECRET'),
    env: 'sandbox', // or 'production'
    timeout: 30
);

$client = new MyLinePayClient($config);
```

### Utilities

[](#utilities)

```
use LinePay\Core\LinePayUtils;

// Generate signature for API requests
$signature = LinePayUtils::generateSignature(
    $channelSecret,
    '/v3/payments/request',
    json_encode($requestBody),
    $nonce
);

// Validate transaction ID format (must be 19 digits)
if (LinePayUtils::isValidTransactionId($transactionId)) {
    // Process transaction
}

// Parse callback query parameters
$result = LinePayUtils::parseConfirmQuery($_GET);
// $result['transactionId'], $result['orderId']
```

### Security: Timing-Safe Signature Verification

[](#security-timing-safe-signature-verification)

The `verifySignature` method uses **constant-time comparison** to prevent timing attacks:

```
use LinePay\Core\LinePayUtils;

// ✓ SECURE: Uses hash_equals() internally (timing-safe)
$isValid = LinePayUtils::verifySignature($secret, $data, $receivedSignature);

// ✗ INSECURE: Never do direct string comparison for signatures
// $isValid = ($expectedSignature === $receivedSignature); // Vulnerable to timing attacks!
```

**Why this matters:** A timing attack can determine how many characters of a signature match by measuring response time. Constant-time comparison always takes the same amount of time regardless of how many characters match.

### Error Handling

[](#error-handling)

LINE Pay API error codes follow a pattern:

Code RangeCategoryDescription`1xxx`AuthenticationChannel ID/Secret issues, invalid signatures`2xxx`PaymentTransaction errors, insufficient balance, expired`9xxx`InternalLINE Pay server errors, maintenance```
use LinePay\Core\Errors\LinePayError;
use LinePay\Core\Errors\LinePayTimeoutError;
use LinePay\Core\Errors\LinePayConfigError;
use LinePay\Core\Errors\LinePayValidationError;

try {
    $response = $client->requestPayment($body);
} catch (LinePayTimeoutError $e) {
    // Handle timeout - IMPORTANT: Check payment status!
    echo "Request timed out after {$e->getTimeout()} seconds";
} catch (LinePayValidationError $e) {
    // Handle validation errors (before API call)
    echo "Invalid input: {$e->getMessage()}";
} catch (LinePayError $e) {
    // Handle API errors
    echo "Error [{$e->getReturnCode()}]: {$e->getReturnMessage()}";

    if ($e->isAuthError()) {
        // 1xxx: Check your Channel ID/Secret, or signature generation
        error_log("Auth failed - verify credentials");
    } elseif ($e->isPaymentError()) {
        // 2xxx: Transaction-specific issue (e.g., already refunded)
        notifyUser("Payment could not be processed");
    } elseif ($e->isInternalError()) {
        // 9xxx: LINE Pay server issue - retry with backoff
        scheduleRetry($body);
    }
} catch (LinePayConfigError $e) {
    // Configuration error (missing/invalid credentials)
    echo "Configuration error: {$e->getMessage()}";
}
```

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

[](#configuration)

ParameterTypeRequiredDefaultDescription`channelId`stringYes-Channel ID from LINE Pay Merchant Center`channelSecret`stringYes-Channel Secret from LINE Pay Merchant Center`env`stringNo`'sandbox'`Environment: `'production'` or `'sandbox'``timeout`intNo`20`Request timeout in secondsRelated Packages
----------------

[](#related-packages)

- [`carllee/line-pay-online-v4`](https://github.com/CarlLee1983/line-pay-online-v4) - LINE Pay Online API V4 client (web/app checkout)
- [`carllee/line-pay-offline-v4`](https://github.com/CarlLee1983/line-pay-offline-v4-php) - LINE Pay Offline API V4 client (POS/Kiosk)

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

[](#development)

```
# Install dependencies
composer install

# Run tests
composer test

# Run tests with coverage
composer test:coverage

# Run static analysis
composer analyze

# Fix code style
composer lint:fix
```

License
-------

[](#license)

MIT License - see the [LICENSE](LICENSE) file for details.

Author
------

[](#author)

Carl Lee - [GitHub](https://github.com/CarlLee1983)

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance73

Regular maintenance activity

Popularity14

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 82.6% 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 ~0 days

Total

2

Last Release

151d ago

### 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 (19 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")

---

Tags

apisdkcorepaymentjapanTaiwanthailandlinev4line pay

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/carllee-line-pay-core-v4/health.svg)

```
[![Health](https://phpackages.com/badges/carllee-line-pay-core-v4/health.svg)](https://phpackages.com/packages/carllee-line-pay-core-v4)
```

###  Alternatives

[checkout/checkout-sdk-php

Checkout.com SDK for PHP

553.3M7](/packages/checkout-checkout-sdk-php)[yidas/line-pay-sdk

LINE Pay SDK for PHP

8428.3k](/packages/yidas-line-pay-sdk)[postfinancecheckout/sdk

PostFinance Checkout SDK for PHP

22219.1k14](/packages/postfinancecheckout-sdk)[wallee/sdk

wallee SDK for PHP

12354.2k11](/packages/wallee-sdk)[blocktrail/blocktrail-sdk

The BlockTrail PHP SDK, for integration of Bitcoin functionality through the BlockTrail API

4921.1k3](/packages/blocktrail-blocktrail-sdk)

PHPackages © 2026

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