LINE Pay SDK for PHP

English | 繁體中文

SDK 版本	Online API 版本	Offline API 版本
v3 (目前版本)	v3	v2
v2	v2	v2

OUTLINE

示範
系統需求
- 授權驗證資訊
安裝
使用方法
外部資源
參考

示範

範例站台程式碼 (Request, 付款, 退款)

// Create LINE Pay client
$linePay = new \yidas\linePay\Client([
    'channelId' => 'Your merchant X-LINE-ChannelId',
    'channelSecret' => 'Your merchant X-LINE-ChannelSecret',
    'isSandbox' => true, 
]);

// Online Request API
$response = $linePay->request([
    'amount' => 250,
    'currency' => 'TWD',
    'orderId' => 'Your order ID',
    'packages' => [
        [
            'id' => 'Your package ID',
            'amount' => 250,
            'name' => 'Your package name',
            'products' => [
                [
                    'name' => 'Your product name',
                    'quantity' => 1,
                    'price' => 250,
                    'imageUrl' => 'https://yourname.com/assets/img/product.png',
                ],
            ],
        ],
    ],
    'redirectUrls' => [
        'confirmUrl' => 'https://yourname.com/line-pay/confirm',
        'cancelUrl' => 'https://yourname.com/line-pay/cancel',
    ],
]);

// Check Request API result (returnCode "0000" check method)
if (!$response->isSuccessful()) {
    throw new Exception("ErrorCode {$response['returnCode']}: {$response['returnMessage']}");
}

// Redirect to LINE Pay payment URL 
header('Location: '. $response->getPaymentUrl() );

LINE Pay API Tool for testing and loging APIs

系統需求

本套件需求:

PHP 5.4.0+|7.0+
guzzlehttp/guzzle 5.3.1+|6.0+
LINE Pay 商家授權驗證資訊

授權驗證資訊

整合 LINE Pay 時所需的驗證資訊如下：

channel id
channel secret key

如何取得授權:

申請 LINE Pay 商家帳號並通過審核，可以參考 LINE Pay 商家中心。
使用商家帳戶登入 LINE Pay 商家後台，取得ChannelId/ChannelSecret (管理付款連結 > 管理連結金鑰)。
於 LINE Pay 商家後台設定伺服器IP白名單 (管理付款連結 > 管理付款伺服器 IP) (v3版本非必要)。

您也可以馬上建立一個Sandbox商家帳號做測試，請參考 LINE Pay - 建立Sandbox。

安裝

在您的專案下執行 Composer 安裝:

composer require yidas/line-pay-sdk ~3.0.0

安裝完成且載入 Composer 後，您即可使用 SDK Class 於您的 PHP 專案：

require __DIR__ . '/vendor/autoload.php';

use yidas\linePay\Client;

使用方法

在使用 LINE Pay SDK 服務之前，您必須先建立與設定一個 Client，在使用這個 Client 去呼叫 API 方法。

Client物件

建立一個 Client 物件並帶入授權驗證資訊：

$linePay = new \yidas\linePay\Client([
    'channelId' => 'Your merchant X-LINE-ChannelId',
    'channelSecret' => 'Your merchant X-LINE-ChannelSecret',
    'isSandbox' => true, 
]);

裝置資訊

您可以於 Client 設定裝置資訊 (非必要)：

$linePay = new \yidas\linePay\Client([
    'channelId' => 'Your merchant X-LINE-ChannelId',
    'channelSecret' => 'Your merchant X-LINE-ChannelSecret',
    'isSandbox' => true, 
    'merchantDeviceType' => 'Device type string',
    'merchantDeviceProfileId' => 'Device profile ID string',
]);

Response物件

每一個API方法皆會回傳 yidas\linePay\Response 物件，可以用來拿取相同於 LINE Pay JSON 回傳資料結構的資料。

取得資料

Response物件提供用陣列或物件的方式來取得回傳資料：

取得為物件

// Get object of response body
$bodyObject = response->toObject();
// Get LINE Pay results code from response
$returnCode = $response->returnCode;
// Get LINE Pay info.payInfo[] from response
$payInfo = $response->info->payInfo;

取得為陣列

// Get array of response body
$bodyArray = response->toArray();
// Get LINE Pay results code from response
$returnCode = $response['returnCode'];
// Get LINE Pay info.payInfo[] from response
$payInfo = $response['info']['payInfo'];

方法

Response物件提供了一些方法幫助使用：

isSuccessful()

LINE Pay API 結果代碼是否成功 (檢查 returnCode 是否為"0000")

Example:

if (!$response->isSuccessful()) {
    
    throw new Exception("Code {$response['returnCode']}: {$response['returnMessage']}");
}

getPaymentUrl()

取得 LINE Pay info.paymentUrl 網址回傳資料 (預設為"web")

getPayInfo()

取得陣列格式的 LINE Pay info.payInfo[] 或 info.[$param1].payInfo[] 回傳資料

toArray()

取得陣列格式的 LINE Pay 回傳資料

toObject()

取得物件格式的 LINE Pay 回傳資料

getStats()

取得\GuzzleHttp\TransferStats物件

Online APIs

線上整合中，商家會 Request 一個付款請求並產生付款 URL(QR code) 提供給消費者用 LINE App 掃描。

流程: 付款Request -> 付款Confirm -> 取得查看付款紀錄 -> 退款

取得查看付款紀錄 API

取得透過 LINE Pay 進行付款的詳細說明。此 API 只會取得已經請款的付款。

public Response details(array $queryParams=null)

Example:

$response = $linePay->details([
    "transactionId" => [$transactionId],
]);

付款request API

在 LINE Pay 中保留付款資訊。在使用 LINE Pay 付款前確認是否為正常的商家，然後保留付款所需的資訊。成功付款 request 後，商家會收到一個「交易編號」，這個鍵值會在付款完成或退款時使用。

public Response request(array $bodyParams=null)

Example:

$response = $linePay->request([
    'amount' => 250,
    'currency' => 'TWD',
    'orderId' => 'Your order ID',
    'packages' => [
        [
            'id' => 'Your package ID',
            'amount' => 250,
            'name' => 'Your package name',
            'products' => [
                [
                    'name' => 'Your product name',
                    'quantity' => 1,
                    'price' => 250,
                    'imageUrl' => 'https://yourname.com/assets/img/product.png',
                ],
            ],
        ],
    ],
    'redirectUrls' => [
        'confirmUrl' => 'https://yourname.com/line-pay/confirm',
        'cancelUrl' => 'https://yourname.com/line-pay/cancel',
    ],
]);

$bodyParams參數規格可以參考 Request API v3 Request Body

付款confirm API

此 API 可讓商家完成付款。商家必須呼叫付款 confirm API，才能實際完成付款。不過，當付款 request 的 "capture" 參數為 "false" 時，付款狀態會變為 "AUTHORIZATION"，只有在呼叫 "請款 API" 後才能完成付款。

public Response confirm(integer $transactionId, array $bodyParams=null)

Example:

$response = $linePay->confirm($transactionId, [
    "amount" => 250,
    "currency" => 'TWD',
]);

退款 API

請求對 LINE Pay 付款完成的項目進行退款。退款時必須提供 LINE Pay 用戶的付款交易編號，也可以視退款金額進行部分退款。

public Response refund(integer $transactionId, array $bodyParams=null)

Example:

$response = $linePay->refund($transactionId);

For Partial refund:

$response = $linePay->refund($transactionId, [
    'refundAmount' => 200,
]);

Check Payment Status API

此API查詢LINE Pay付款請求狀態。不經過confirmUrl，商加隔一段時間直接檢查付款狀態，查看用戶是否確認付款，最終判斷付款流程是否完成。

public Response check(integer $transactionId)

Example:

$response = $linePay->check($transactionId);

請款 API

如果商家呼叫付款 request API 時 "capture" 為 "false"，則只有呼叫請款 API 後才能完成付款。 confirm API 執行結果只有授權的付款進行請款動作。

public Response authorizationsCapture(integer $transactionId, array $bodyParams=null)

Example:

$response = $linePay->authorizationsCapture($transactionId, [
    "amount" => 250,
    "currency" => 'TWD',
]);

授權作廢 API

將已授權的交易作廢。將先前已授權的付款作廢。已經請款的付款可以藉由使用「退款 API」進行退款。

public Response authorizationsVoid(integer $transactionId, array $bodyParams=null)

Example:

$response = $linePay->authorizationsVoid($transactionId);

自動付款 API

當付款 request API 的付款類型設定為 PREAPPROVED 時，regKey 會隨付款結果傳回。自動付款 API 會使用 regKey 直接完成付款，無需使用 LINE 應用程式。

public Response preapproved(integer $regKey, array $bodyParams=null)

Example:

$response = $linePay->preapproved([
    'productName' => 'Your product name',
    'amount' => 250,
    'currency' => 'TWD',
    'orderId' => 'Your order ID',
]);

查看 regKey 狀態 API

使用自動付款 API 前，檢查 regKey 是否存在。

public Response preapprovedCheck(integer $regKey, array $queryParams=null)

Example:

$response = $linePay->preapprovedCheck($regKey);

註銷 regKey API

註銷為自動付款登錄的 regKey 資訊。一旦呼叫此 API，現有的 regKey 將無法繼續用於自動付款。

public Response preapprovedExpire(integer $regKey, array $bodyParams=null)

Example:

$response = $linePay->preapprovedExpire($regKey);

Offline APIs

線下整合中，可由LINE Pay用戶主頁面"我的條碼"產生一維碼或QR碼給 POS 設備掃描。

流程: OneTimeKeysPay -> OrdersCheck -> OrdersRefund

Payment

此API為商店交易裝置讀取LINE Pay"我的條碼"後傳送付款要求所需的API。

public Response oneTimeKeysPay(array $bodyParams=null)

Example:

$response = $linePay->oneTimeKeysPay([
    'productName' => 'Your product name',
    'amount' => 250,
    'currency' => 'TWD',
    'productImageUrl' => 'https://yourname.com/assets/img/product.png',
    'orderId' => 'Your order ID',
    "oneTimeKey"=> 'LINE Pay MyCode',
]);

Payment Status Check

如果因為回應時間過長導致最終付款狀態無法確認時，請使用這支API

交易狀態應在固定的時間間隔中被檢查，建議 3~5 秒即檢查一次。
付款的有效期間為"線下付款API" Response時間後20分鐘內，因此商家最長應檢查交易狀態20分鐘。若超過20分鐘，該筆交易則被取消

public Response ordersCheck(string $orderId, array $$queryParams=null)

Example:

$response = $linePay->ordersCheck($orderId);

Void

此API用於進行授權作廢

public Response ordersVoid(string $orderId, array $bodyParams=null)

Example:

$response = $linePay->ordersVoid($orderId);

Capture

此API用於對已取得授權的交易進行請款。

public Response ordersCapture(string $orderId, array $bodyParams=null)

Example:

$response = $linePay->ordersCapture($orderId);

Refund

此API對付款完成的項目進行退款。

public Response ordersRefund(string $orderId, array $bodyParams=null)

Example:

$response = $linePay->ordersRefund($orderId);

取得查看授權記錄 API

此API用於查看已取得付款授權交易的交易記錄。只有授權或取消授權 (作廢或是過期) 的交易記錄才可使用此API查詢，已經請款的交易紀錄則需使用「查看付款紀錄 API」來查詢。

public Response authorizations(array $queryParams=null)

Example for searching transactionId:

$response = $linePay->authorizations([
    "transactionId" => [$transactionId],
]);

Example for searching orderId:

$response = $linePay->authorizations([
    "orderId" => $orderId,
]);

EXCEPTIONS

Client會在API串接處理期間發生錯誤時拋出異常。

ConnectException

yidas\linePay\exception\ConnectException 當出現網路錯誤(如Timeout)時會拋出異常。

try {

    $response = $linePay->confirm($transactionId, $bodyParams);
    
} catch (\yidas\linePay\exception\ConnectException $e) {

    // Process of confirm API timeout handling
}

外部資源

LINE Pay Online API v3 整合指南 (TW)

LINE Pay Offline API v2 整合指南 (TW)

LINE Pay Sandbox 商家帳號建立申請

LINE Pay OneTimeKeys 產生器 (台灣商家使用)

LINE Pay Online API v2 技術文件 PDF版本下載 (多國語言)

參考

LINE Pay Developers - APIs

Files

README-zh_TW.md

Latest commit

History

README-zh_TW.md

File metadata and controls

LINE Pay SDK for PHP

OUTLINE

示範

系統需求

授權驗證資訊

安裝

使用方法

Client物件

裝置資訊

Response物件

取得資料

取得為物件

取得為陣列

方法

isSuccessful()

getPaymentUrl()

getPayInfo()

toArray()

toObject()

getStats()

Online APIs

取得查看付款紀錄 API

付款request API

付款confirm API

退款 API

Check Payment Status API

請款 API

授權作廢 API

自動付款 API

查看 regKey 狀態 API

註銷 regKey API

Offline APIs

Payment

Payment Status Check

Void

Capture

Refund

取得查看授權記錄 API

EXCEPTIONS

ConnectException

外部資源

參考