README

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 | 繁體中文 | 日本語 | ภาษาไทย

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

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

Requirements

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

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
• For offline payments (POS/Kiosk): carllee/line-pay-offline-v4

Use this package directly only if you need to build a custom LINE Pay client with specialized behavior.

Usage

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

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

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

LINE Pay API error codes follow a pattern:

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

Related Packages

• carllee/line-pay-online-v4 - LINE Pay Online API V4 client (web/app checkout)
• carllee/line-pay-offline-v4 - LINE Pay Offline API V4 client (POS/Kiosk)

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

MIT License - see the LICENSE file for details.

Author

Carl Lee - GitHub