README

使用WebService或Webpay扩展实现St.George互联网支付网关的PHP客户端。

使用此库，您可以为St.George发行的凭据提供支持，并立即开始刷卡。

该库支持网关的所有功能，包括

• 购买和退款
• 预授权和完成
• 检查现有交易的状态
• 在交易上设置客户引用
• 在交易上设置注释
• 在交易上设置商家描述（将显示在客户的银行对账单上）

该库有2个提供者用于连接到St.George

• WebService
• 扩展

WebService

WebService是最容易集成的，只需使用简单的HTTP客户端连接到St.George公开的API。

要求

• PHP >= 5.6
• Composer

如果您在OS X上使用WebService提供程序遇到SSL连接问题，请检查此支持线程。

安装

您可以使用Composer在项目中安装库

composer require mitchdav/st-george-ipg

初始化客户端

WebService需要2个凭据，即您的St.George发行的客户ID和认证令牌。

将您的客户ID复制到IPG_CLIENT_ID环境变量中，或修改下面的代码。

您可以在商家管理控制台登录，点击商家详情，然后在右侧的IPG账户下，点击您的客户ID，然后转到认证选项卡。

在左侧的列表中，单击配置旁边的安全令牌，并生成一个令牌。将此值复制到IPG_AUTHENTICATION_TOKEN环境变量中，或修改下面的代码。

然后您可以使用以下方式初始化客户端

<?php

use StGeorgeIPG\Client;
use StGeorgeIPG\Providers\WebService;

$clientId            = getenv('IPG_CLIENT_ID');
$authenticationToken = getenv('IPG_AUTHENTICATION_TOKEN');

$webService = new WebService();

$webService->setClientId($clientId)
           ->setAuthenticationToken($authenticationToken);

$client = new Client($webService);

扩展

扩展更难集成，需要您编译和安装PHP扩展。

要求

• PHP 5.6（不幸的是，Webpay扩展目前不支持PHP 7.0+，因此此提供程序受限于相同的要求）
• Composer
• Linux操作系统（受Webpay限制）
• Webpay 库编译和安装（有关如何主要自动化的说明，请参阅下方的Docker 部分）

安装

您可以使用Composer在项目中安装库

composer require mitchdav/st-george-ipg

接下来，您需要编译和安装 Webpay PHP 扩展，这将在下面进行说明。

初始化客户端

扩展需要2个凭证，分别是您的 St.George 发行的客户端ID、您的证书密码，以及可选的认证令牌。

将您的客户ID复制到IPG_CLIENT_ID环境变量中，或修改下面的代码。

将您的证书密码复制到 IPG_CERTIFICATE_PASSWORD 环境变量中，或者修改下面的代码。

如果您之前设置了认证令牌，您可以通过登录到 商户管理控制台，点击 商户详情，然后在右侧的 IPG 账户 下，点击您的客户端ID，然后转到 认证 选项卡来找到它。

在左侧的列表中，单击配置旁边的安全令牌，并生成一个令牌。将此值复制到IPG_AUTHENTICATION_TOKEN环境变量中，或修改下面的代码。

如果您从未设置认证令牌，此步骤是可选的，交易无需它即可成功完成。如果您已设置（例如，如果您正在测试 WebService 提供商），则必须在扩展中设置它。

如果您的证书安装到了一个单独的位置，您可以将路径设置到 IPG_CERTIFICATE_PATH 环境变量中，或者修改下面的代码。

然后您可以使用以下方式初始化客户端

<?php

use StGeorgeIPG\Client;
use StGeorgeIPG\Providers\Extension;

$clientId            = getenv('IPG_CLIENT_ID');
$authenticationToken = getenv('IPG_AUTHENTICATION_TOKEN');
$certificatePassword = getenv('IPG_CERTIFICATE_PASSWORD');
$certificatePath     = getenv('IPG_CERTIFICATE_PATH');

if (!$certificatePath) {
    $certificatePath = 'cert.cert';
}

$extension = new Extension();

$extension->setClientId($clientId)
          ->setAuthenticationToken($authenticationToken)
          ->setCertificatePassword($certificatePassword)
          ->setCertificatePath($certificatePath);

$client = new Client($extension);

用法

客户端提供辅助方法来构建一个有效的请求。对于每种请求类型，都有比下面显示的更多选项，因此请检查 客户端 了解如何可选地设置 CVC2（例如）或商户描述。

创建请求后，您需要在请求上调用 $client->execute($request) 来获取响应。如果交易失败，响应代码将映射到不同的异常，如下面所示。如果没有抛出异常，则表示交易成功。

向客户收费（购买）

使用初始化后的客户端，您可以像这样向客户收费

use Carbon\Carbon;
use StGeorgeIPG\Exceptions\ResponseCodes\Exception;

$oneYearAhead = (new Carbon())->addYear();

$amount     = 10.00; // In dollars
$cardNumber = '4111111111111111';
$month      = $oneYearAhead->month;
$year       = $oneYearAhead->year;

$purchaseRequest = $client->purchase($amount, $cardNumber, $month, $year);

try {
    $purchaseResponse = $client->execute($purchaseRequest);

    echo 'The charge was successful.' . "\n";
} catch (Exception $ex) {
    echo 'The charge was unsuccessful.' . "\n";
    echo $ex->getMessage() . "\n";

    var_dump($purchaseRequest);
    var_dump($ex->getResponse());
}

退款

您可以在收费后向客户退款，如下所示

use Carbon\Carbon;
use StGeorgeIPG\Exceptions\ResponseCodes\Exception;

$oneYearAhead = (new Carbon())->addYear();

$amount     = 10.00; // In dollars
$cardNumber = '4111111111111111';
$month      = $oneYearAhead->month;
$year       = $oneYearAhead->year;

$purchaseRequest = $client->purchase($amount, $cardNumber, $month, $year);

try {
    $purchaseResponse = $client->execute($purchaseRequest);

    echo 'The charge was successful.' . "\n";

    $refundRequest = $client->refund(5.00, $purchaseResponse->getTransactionReference()); // In dollars

    try {
        $refundResponse = $client->execute($refundRequest);

        echo 'The refund was successful.' . "\n";
    } catch (Exception $ex) {
        echo 'The refund was unsuccessful.' . "\n";
        echo $ex->getMessage() . "\n";

        var_dump($refundRequest);
        var_dump($ex->getResponse());
    }
} catch (Exception $ex) {
    echo 'The charge was unsuccessful.' . "\n";
    echo $ex->getMessage() . "\n";

    var_dump($purchaseRequest);
    var_dump($ex->getResponse());
}

预先授权

您还可以预先授权收费（如果您的账户已启用），这相当于对客户的卡进行保留，如下所示

use Carbon\Carbon;
use StGeorgeIPG\Exceptions\ResponseCodes\Exception;

$oneYearAhead = (new Carbon())->addYear();

$amount     = 10.00; // In dollars
$cardNumber = '4111111111111111';
$month      = $oneYearAhead->month;
$year       = $oneYearAhead->year;

$preAuthRequest = $client->preAuth($amount, $cardNumber, $month, $year);

try {
    $preAuthResponse = $client->execute($preAuthRequest);

    echo 'The pre-authorisation was successful.' . "\n";
} catch (Exception $ex) {
    echo 'The pre-authorisation was unsuccessful.' . "\n";
    echo $ex->getMessage() . "\n";

    var_dump($preAuthRequest);
    var_dump($ex->getResponse());
}

完成

预先授权成功后，您可以像这样完成交易

use Carbon\Carbon;
use StGeorgeIPG\Exceptions\ResponseCodes\Exception;

$oneYearAhead = (new Carbon())->addYear();

$amount     = 10.00; // In dollars
$cardNumber = '4111111111111111';
$month      = $oneYearAhead->month;
$year       = $oneYearAhead->year;

$preAuthRequest = $client->preAuth($amount, $cardNumber, $month, $year);

try {
    $preAuthResponse = $client->execute($preAuthRequest);

    echo 'The pre-authorisation was successful.' . "\n";

    $completionRequest = $client->completion($amount, $preAuthResponse->getTransactionReference(), $preAuthResponse->getAuthorisationNumber()); // In dollars

    try {
        $completionResponse = $client->execute($completionRequest);

        echo 'The completion was successful.' . "\n";
    } catch (Exception $ex) {
        echo 'The completion was unsuccessful.' . "\n";
        echo $ex->getMessage() . "\n";

        var_dump($completionRequest);
        var_dump($ex->getResponse());
    }
} catch (Exception $ex) {
    echo 'The pre-authorisation was unsuccessful.' . "\n";
    echo $ex->getMessage() . "\n";

    var_dump($preAuthRequest);
    var_dump($ex->getResponse());
}

处理错误

如果请求不成功，库将抛出异常，这使得确定交易结果变得容易。

常见的错误代码，如客户资金不足或使用无效的卡号时，已经为您映射到可自由使用的特殊异常。这些特殊异常是 \StGeorge\Exceptions\ResponseCodes\Exception 的实例，允许您调用 $ex->getResponse() 来获取响应。通过捕获这个异常，您可以捕获所有获得响应的错误。

对于未获得响应的错误，例如交易失败或经过3次状态检查后仍处于进行中，将调用其他异常，因此请检查Client 类以获取更多详细信息（在 getResponse() 方法中）。您可以使用通用 \Exception 类来捕获这些异常。

如果有本地错误，由响应代码 -1 表示，异常将映射到 \StGeorge\Exceptions\ResponseCodes\LocalErrors\Exception 的实例，具体异常在 本地错误 文件夹中。这些异常通常表示连接问题，或客户端ID或证书密码的问题。

测试

现在您已经安装好了，可以运行以下测试命令

• composer test 来运行所有可用的测试套件
• composer test:unit 来运行单元测试套件
• composer test:integration 来运行集成测试套件
• composer test:end-to-end 来运行端到端测试套件

端到端测试套件连接到 St.George 的测试服务器，以运行 00 - 99 所有响应代码的测试交易，因此要运行此测试套件，您需要安装 Webpay 并设置您的 IPG_CLIENT_ID 和 IPG_AUTHENTICATION_TOKEN（对于 WebService）或 IPG_CERTIFICATE_PASSWORD（对于 Extension）环境变量。

安装 Webpay

注意： 截至 2017 年 7 月，这些说明（包括 Docker 和手动安装）都可以正确连接到 St.George。不幸的是，在此日期之后运行它们时，它们仍然可以正确编译和安装，但在连接到 St.George IPG 服务器时，将出现 SSL 连接错误，我无法解决这个问题。 如果您找到解决方案，请告诉我。

使用 Docker 安装

手动安装 Webpay 库非常痛苦，因此提供了一个 Dockerfile，可以帮助您 主要 设置。

您可以使用此存储库中的 Dockerfile 来构建它

docker build -t mitchdav/st-george-ipg .

一旦您有了构建的容器，您可以使用以下方法运行它

docker run -e IPG_CLIENT_ID='10000000' -e IPG_CERTIFICATE_PASSWORD='password' -i -t mitchdav/st-george-ipg /bin/bash

其中您需要用自己的 St.George 提供的客户端 ID 和证书密码替换。

手动安装

如果您无法使用 Docker，可以按照以下指南在全新的 AWS EC2 安装 Ubuntu 16.04（目前 AMI ami-96666ff5）上运行命令。对于所有其他安装，您需要阅读Linux API 开发者指南并自行解决任何问题。

sudo apt-get update -y
sudo apt-get install -y python-software-properties
sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update -y
sudo apt-get install -y swig gcc unzip php5.6 php5.6-cli php5.6-common php5.6-mbstring php5.6-gd php5.6-intl php5.6-xml php5.6-mysql php5.6-mcrypt php5.6-zip php5.6-dev composer
sudo ln -s /lib/x86_64-linux-gnu/libcrypto.so.1.0.0 /lib/libcrypto.so.6
sudo ln -s /lib/x86_64-linux-gnu/libssl.so.1.0.0 /lib/libssl.so.6
wget https://www.ipg.stgeorge.com.au/downloads/StGeorgeLinuxAPI-3.3.tar.gz
tar -xzvf StGeorgeLinuxAPI-3.3.tar.gz
cd webpaySWIG-3.3/
sed -i 's\PHP_EXTENSIONS  = /usr/lib64/php/modules\PHP_EXTENSIONS  = /usr/lib/php/20131226\g' makefilePhp5
sed -i 's\PHP_INCLUDE_DIR = /usr/include/php/\PHP_INCLUDE_DIR = /usr/include/php/20131226/\g' makefilePhp5
sudo make -f makefilePhp5
sudo echo "extension=webpay_php.so" >> /etc/php/5.6/cli/php.ini
php -i | grep webpay

如果您已成功安装库，您将看到最后一条命令的输出如下

webpay
Client Type => webpayPHP5
Webpay PHP Library => webpay_php.so
Webpay Core Library => libwebpayclient.so

然后您需要下载证书，在您打算运行项目的任何目录中使用以下命令

wget https://www.ipg.stgeorge.com.au/downloads/cert.zip
unzip cert.zip

注意，当使用 Docker 安装时，此操作会自动为您完成。

最后，按照如下方式导出St.George提供的客户端ID和证书密码

export IPG_CLIENT_ID='10000000'
export IPG_CERTIFICATE_PASSWORD='password'

以下是一些有用的Stack Overflow问题，可用于故障排除

• wrap_newBundle在SWIG和webpay中不可用
• 能否使用PHP安装webpay扩展？

更多信息

关于St.George互联网支付网关的更多信息，请参考此处。相关的文件包括

• 通用API开发者指南
• Linux API开发者指南
• IPG响应代码表