README

LINE Pay SDK for PHP

PHP版的LINE Pay SDK

英文 | 繁體中文

概述

• 演示
• 需求
  • 认证
• 安装
• 用法
  • 客户端
    • 设备信息
  • 响应
    • 获取数据
      • 按对象获取
      • 按数组获取
    • 方法
      • isSuccessful()
      • getPaymentUrl()
      • getPayInfo()
      • toArray()
      • toObject()
      • getStats()
  • 在线API
    • 支付详情API
    • 请求API
    • 确认API
    • 退款API
    • 检查支付状态API
    • 捕获API
    • 作废API
    • 预批准支付API
    • 检查RegKey API
    • 过期RegKey API
  • 离线API
    • 支付
    • 支付状态检查
    • 作废
    • 捕获
    • 退款
    • 授权详情
  • 异常
    • ConnectException
• 资源
• 参考

演示

LINE Pay (请求、确认、退款) 示例代码站点

// 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 测试和日志工具

需求

此库需要以下内容

• PHP 5.4.0+|7.0+
• guzzlehttp/guzzle 5.3.1+|6.0+
• LINE Pay 商户认证

认证

每个 LINE Pay 商户都需要认证信息以集成 LINE Pay，如下所示

• 渠道ID
• 渠道密钥

获取 LINE Pay 认证

1. 商家验证信息可以在评估流程完成后在 LINE Pay 商户中心 查看。
2. 登录到 LINE Pay 商户中心，然后 获取 ChannelId/ChannelSecret（支付集成管理 > 管理链接密钥）。
3. 在 LINE Pay 商户中心 中，为您的服务器 设置 IP 白名单（支付集成管理 > 管理支付服务器 IP）（v3 不需要）。

您可以通过 LINE Pay 沙盒创建 立即创建一个沙盒商户账户进行测试。

安装

在您的项目中运行 Composer

composer require yidas/line-pay-sdk ~3.0.0

然后您可以在 PHP 项目中加载 Composer 后使用 SDK 类

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

use yidas\linePay\Client;

用法

在使用任何 API 方法之前，您首先需要创建一个带有配置的客户端，然后使用该客户端访问 LINE Pay API 方法。

客户端

使用 API 认证 创建 LINE Pay 客户端

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

设备信息

您可以为客户端设置设备信息（可选）

$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',
]);

响应

每个 API 方法都将返回 yidas\linePay\Response 对象，可以检索到与 LINE Pay JSON 响应数据结构相关的数据。

获取数据

响应对象提供通过对象属性或数组键访问响应体数据的方式

按对象获取

// 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'];

方法

响应对象提供一些有用的方法来使用

isSuccessful()

LINE Pay API 结果成功状态（检查返回码是否为 "0000"）

示例

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

getPaymentUrl()

获取 LINE Pay API 响应体的 info.paymentUrl（默认类型为 "web"）

getPayInfo()

获取 LINE Pay API 响应体的 info.payInfo[] 或 info.[$param1].payInfo[] 作为数组

toArray()

获取 LINE Pay 响应体作为数组

toObject()

获取 LINE Pay 响应体作为对象

getStats()

获取 \GuzzleHttp\TransferStats 对象

在线API

对于 Web 集成。商家将请求支付并生成支付 URL（二维码），由 LINE App 的客户扫描。

流程：请求 -> 确认 -> 详情 -> 退款

支付详情API

获取使用LINE Pay进行的支付详情。此API仅获取已捕获的支付。

public Response details(array $queryParams=null)

示例

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

请求API

在处理使用LINE Pay的支付之前，商户将被评估是否为普通商户店铺，然后请求支付信息。当支付请求成功时，商户将获得一个“transactionId”，这是一个在支付完成或退款之前使用的键值。

public Response request(array $bodyParams=null)

示例

$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规范可以参考请求API v3请求正文

确认API

此API用于商户完成其支付。商户必须调用确认支付API以实际完成支付。然而，当支付预约中的“capture”参数为“false”时，支付状态变为授权，只有调用“捕获API”后，支付才完成。

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

示例

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

退款API

请求使用LINE Pay进行的支付退款。要退款，必须转发LINE Pay用户的支付交易Id。根据退款金额，也可以进行部分退款。

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

示例

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

对于部分退款

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

检查支付状态API

这是一个检查LINE Pay支付请求状态的API。商户应定期检查用户支付确认状态（不使用ConfirmURL）并决定是否可以完成支付。

public Response check(integer $transactionId)

示例

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

捕获API

当商户调用“请求API”时，“capture”为“false”，只有在调用捕获API后，支付才完成。

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

示例

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

作废API

取消先前授权的支付。可以使用“退款API”对已捕获的支付进行退款。

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

示例

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

预批准支付API

当请求API的支付类型设置为预批准时，支付结果将返回一个regKey。预批准支付API使用此regKey直接完成支付，而无需使用LINE应用。

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

示例

$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)

示例

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

过期RegKey API

使预批准支付注册的regKey信息过期。一旦调用API，regKey就不再用于预批准支付。

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

示例

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

离线API

对于POS集成。客户向商户出示其条形码或二维码，以便在POS机上扫描。

流程：一次性密钥支付 -> 订单检查 -> 订单退款

支付

此API是通过读取来自LINE Pay应用的MyCode，使用商户的设备进行支付处理的。

public Response oneTimeKeysPay(array $bodyParams=null)

示例

$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',
]);

支付状态检查

这是在读取超时时无法检查最终支付状态时使用的API。

• 需要定期调用它来检查状态，建议间隔时间为3~5秒。
• 支付有效时间最长为20分钟，从支付API响应时间开始计算。因此，商户应最多检查20分钟的支付状态。如果超过20分钟，则该交易将是因为有效时间过长而无法完成的支付。

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

示例

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

作废

此API用于取消授权。

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

示例

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

捕获

此API用于捕获授权交易。

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

示例

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

退款

此API在支付完成后进行退款（捕获数据）。

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

示例

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

授权详情

此API用于搜索授权详情。只能搜索授权或已取消（作废或过期）的数据，而捕获后的数据可以通过支付详情API进行搜索。

public Response authorizations(array $queryParams=null)

搜索transactionId的示例

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

搜索orderId的示例

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

异常

客户端抛出异常，以处理API交易期间发生的错误。

ConnectException

在网络错误（超时）的情况下，抛出yidas\linePay\exception\ConnectException异常。

try {

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

    // Process of confirm API timeout handling
}

资源

LINE Pay 在线API v3指南（英文）

LINE Pay 线下API v2指南（英文）

创建LINE Pay沙盒

LINE Pay OneTimeKeys模拟

LINE Pay OneTimeKeys模拟（适用于台湾商户）

LINE Pay 在线API v2文档PDF版本（多语言）

参考文献

LINE Pay 开发者 - API