README

一个易于使用、一致的PHP支付处理库

Omnipay是一个PHP支付处理库。它基于来自Active Merchant的想法以及为[CI Merchant]实现几十个网关的经验而设计。它有一个清晰和一致的API，完全单元测试，并且还提供了一个示例应用程序以帮助您入门。

为什么使用Omnipay而不是网关的官方PHP包/示例代码？

因为你可以学习一个API，并在多个使用不同支付网关的项目中使用它
因为如果你需要更改支付网关，你不需要重写你的代码
因为大多数官方PHP支付网关库都很混乱
因为大多数支付网关的文档非常差
因为你正在编写一个购物车，需要支持多个网关

TL;DR

只想看看一些代码？

use Omnipay\Omnipay;

$gateway = Omnipay::create('Stripe');
$gateway->setApiKey('abc123');

$formData = array('number' => '4242424242424242', 'expiryMonth' => '6', 'expiryYear' => '2030', 'cvv' => '123');
$response = $gateway->purchase(array('amount' => '10.00', 'currency' => 'USD', 'card' => $formData))->send();

if ($response->isRedirect()) {
    // redirect to offsite payment gateway
    $response->redirect();
} elseif ($response->isSuccessful()) {
    // payment was successful: update database
    print_r($response);
} else {
    // payment failed: display message to customer
    echo $response->getMessage();
}

如你所见，Omnipay有一个一致、经过深思熟虑的API。我们试图尽可能抽象不同支付网关之间的差异。

包布局

Omnipay是一组包，所有这些包都依赖于omnipay/common包以提供一致的接口。没有对官方支付网关PHP包的依赖 - 我们更喜欢直接使用HTTP API。在底层，我们使用流行的、强大的PHP-HTTP库来发送HTTP请求。默认情况下，使用league/omnipay时需要Guzzle适配器。

可以通过克隆现有包的布局来创建新的网关。在为你的包选择名称时，请勿使用omnipay供应商前缀，因为这暗示它是官方支持的。你应该使用你自己的用户名作为供应商前缀，并在包名前加上omnipay-以使其明确表示你的包与Omnipay兼容。例如，如果你的GitHub用户名是santa，并且你正在实现giftpay支付库，你的composer包的好名称可以是santa/omnipay-giftpay。

安装

Omnipay通过Composer安装。对于大多数用途，你需要要求league/omnipay和单个网关

composer require league/omnipay:^3 omnipay/paypal

如果你想使用自己的HTTP客户端而不是Guzzle（这是league/omnipay的默认设置），你可以要求omnipay/common和任何php-http/client-implementation（请参阅PHP Http）

composer require league/common:^3 omnipay/paypal php-http/buzz-adapter

从v2升级到v3

如果你的网关支持v3，你可以要求该版本。确保你要求league/omnipay或单独的Http适配器。

如果没有v3的版本，请提出一个issue或自行升级网关并创建一个PR。请参阅omnipay/common的升级指南

注意：包名已从 omnipay/omnipay 更改为 league/omnipay 以适应v3版本。

支付网关

所有支付网关都必须实现 GatewayInterface 接口，并且通常扩展 AbstractGateway 以实现基本功能。

以下网关可供使用

网关的创建和初始化如下

use Omnipay\Omnipay;

$gateway = Omnipay::create('PayPal_Express');
$gateway->setUsername('adrian');
$gateway->setPassword('12345');

大多数设置都是网关特定的。如果您需要查询网关以获取可用设置的列表，可以调用 getDefaultParameters()

$settings = $gateway->getDefaultParameters();
// default settings array format:
array(
    'username' => '', // string variable
    'testMode' => false, // boolean variable
    'landingPage' => array('billing', 'login'), // enum variable, first item should be treated as default
);

通常，大多数支付网关可以分为以下两种类型

离线网关，例如PayPal Express，其中客户将被重定向到第三方网站输入付款详情
在线（商家托管）网关，例如PayPal Pro，其中客户在您的网站上输入他们的信用卡详情

然而，有些网关，如Sage Pay Direct，您可以在网站上获取信用卡详情，然后根据客户的卡是否支持3D Secure认证选择性地进行重定向。因此，没有必要区分这两种类型的网关（除了支持的方法之外）。

信用卡/付款表单输入

用户表单输入被引导到 CreditCard 对象。这提供了一种安全的方式来接受用户输入。

CreditCard 对象具有以下字段

firstName
lastName
number
expiryMonth
expiryYear
startMonth
startYear
cvv
issueNumber
type
billingAddress1
billingAddress2
billingCity
billingPostcode
billingState
billingCountry
billingPhone
shippingAddress1
shippingAddress2
shippingCity
shippingPostcode
shippingState
shippingCountry
shippingPhone
company
email

即使离线网关也使用了 CreditCard 对象，因为通常您需要通过网关传递客户的账单或发货详情。

您可以通过构造函数使用不受信任的用户输入初始化 CreditCard 对象。传递给构造函数且不被识别的字段将被忽略。

$formInputData = array(
    'firstName' => 'Bobby',
    'lastName' => 'Tables',
    'number' => '4111111111111111',
);
$card = new CreditCard($formInputData);

您也可以直接将表单数据数组传递给网关，网关将为您创建一个 CreditCard 对象。

可以使用获取器和设置器访问 CreditCard 字段

$number = $card->getNumber();
$card->setFirstName('Adrian');

如果您提交明显无效的信用卡详情（缺少必填字段或失败的Luhn检查的号码），将抛出 InvalidCreditCardException。您应该在将详情提交到您的网关之前，使用您的框架的验证库验证卡详情，以避免不必要的API调用。

对于在线支付网关，以下卡字段通常是必需的

firstName
lastName
number
expiryMonth
expiryYear
cvv

您也可以通过调用 Helper::validateLuhn($number) 使用Luhn算法验证卡号。

网关方法

网关实现的主要方法包括

authorize($options) - 在客户的卡上授权一定金额
completeAuthorize($options) - 处理授权后的离线网关返回
capture($options) - 捕获您之前已授权的金额
purchase($options) - 在客户的卡上授权并立即捕获一定金额
completePurchase($options) - 处理购买后的离线网关返回
refund($options) - 退款已处理的交易
void($options) - 通常只能在提交交易后24小时内调用
acceptNotification() - 将来自离线网关的传入请求转换为通用通知对象以进行进一步处理
createCard - 获取一个可用来进行未来支付的 cardReference。例如，这可能用于月度账单场景。

现场网关不需要实现 completeAuthorize 和 completePurchase 方法。未收到支付通知的网关不需要实现 acceptNotification。如果任何网关不支持某些功能（例如退款），则将抛出 BadMethodCallException。

除了 acceptNotification 之外的所有网关方法都接受一个 $options 数组作为参数。acceptNotification 方法不接受任何参数，并将隐式访问 HTTP URL 变量或 POST 数据。每个网关所必需的参数可能不同，如果省略了任何必需的参数，网关将抛出 InvalidRequestException。所有网关都将接受这些选项的一个子集

card
token
amount
currency
description
transactionId
clientIp
returnUrl
cancelUrl

像这样将选项传递给方法

$card = new CreditCard($formData);
$request = $gateway->authorize(array(
    'amount' => '10.00', // this represents $10.00
    'card' => $card,
    'returnUrl' => 'https://www.example.com/return',
));

在调用 completeAuthorize 或 completePurchase 方法时，应该提供与最初进行 authorize 或 purchase 调用时完全相同的参数（一些网关可能需要验证例如实际支付的金额等于请求的金额）。您可以省略的唯一参数是 card。

为了总结您可用的各种参数

网关设置（例如用户名和密码）直接在网关上设置。这些设置适用于所有支付，并且通常您会将这些存储在配置文件或数据库中。
方法选项用于任何特定于支付的选择，这些选择不是由客户设置的。例如，支付的 amount、currency、transactionId 和 returnUrl。
信用卡参数是用户提供的数据。例如，您希望用户指定他们的 firstName 和 billingCountry，但您不希望用户指定支付 currency 或 returnUrl。

支付响应

支付响应必须实现 ResponseInterface。有两种主要类型的响应

支付成功（标准响应）
网站需要重定向到站外支付表单（重定向响应）

成功的响应

对于成功的响应，通常将生成一个引用，可用于稍后捕获或退款交易。以下方法总是可用

$response = $gateway->purchase(array('amount' => '10.00', 'card' => $card))->send();

$response->isSuccessful(); // is the response successful?
$response->isRedirect(); // is the response a redirect?
$response->getTransactionReference(); // a reference generated by the payment gateway
$response->getTransactionId(); // the reference set by the originating website if available.
$response->getMessage(); // a message generated by the payment gateway

此外，大多数网关将覆盖响应对象，并提供了访问网关返回的任何额外字段。如果支付授权是可重复使用的，网关将实现 $response->getCardReference();。此方法自 3.1.1 版以来始终可用（但可能返回 NULL）。

重定向响应

重定向响应根据客户的浏览器是否必须使用 GET（RedirectResponse 对象）或 POST（FormRedirectResponse）进行重定向进一步细分。这些可以潜在地组合成一个单一的响应类，具有 getRedirectMethod()。

在处理支付后，购物车应检查响应是否需要重定向，如果是，则相应地进行重定向

$response = $gateway->purchase(array('amount' => '10.00', 'card' => $card))->send();
if ($response->isSuccessful()) {
    // payment is complete
} elseif ($response->isRedirect()) {
    $response->redirect(); // this will automatically forward the customer
} else {
    // not successful
}

客户不会自动跳转，因为通常购物车或开发人员会想自定义重定向方法（如果支付处理在 AJAX 调用内部进行，他们希望将 JS 返回到浏览器）。

要显示自己的重定向页面，只需在响应上调用 getRedirectUrl()，然后相应地显示它。

$url = $response->getRedirectUrl();
// for a form redirect, you can also call the following method:
$data = $response->getRedirectData(); // associative array of fields which must be posted to the redirectUrl

错误处理

您可以通过在响应对象上调用isSuccessful()来测试响应是否成功。如果与网关通信出错，或者您的请求明显无效，将会抛出异常。一般来说，如果网关没有抛出异常，但返回了不成功的响应，那么这是您应该显示给客户的消息。如果抛出异常，可能是您的代码中存在错误（缺少必填字段），或者与网关的通信出错。

您可以通过将整个请求包裹在try-catch块中处理这两种情况。

try {
    $response = $gateway->purchase(array('amount' => '10.00', 'card' => $card))->send();
    if ($response->isSuccessful()) {
        // mark order as complete
    } elseif ($response->isRedirect()) {
        $response->redirect();
    } else {
        // display error to customer
        exit($response->getMessage());
    }
} catch (\Exception $e) {
    // internal error, log exception and display a generic message to the customer
    exit('Sorry, there was an error processing your payment. Please try again later.');
}

测试模式和开发者模式

大多数网关允许您设置沙箱或开发者账户，使用不同的URL和凭证。一些还允许您对实时站点进行测试交易，这不会导致实时交易。

仅实现开发者账户的网关（其中大多数）将其称为testMode。然而，Authorize.net实现了两种模式，并将其称为developerMode。

在实现多个网关时，您应该使用类似以下的结构

if ($is_developer_mode) {
    if (method_exists($gateway, 'setDeveloperMode')) {
        $gateway->setDeveloperMode(TRUE);
    } else {
        $gateway->setTestMode(TRUE);
    }
}

令牌计费

令牌计费允许您将信用卡存储在您的网关中，并在稍后进行计费。并非所有网关都支持令牌计费。对于支持的网关，以下方法可用：

createCard($options) - 返回一个包含cardReference的响应对象，该对象可用于未来的交易
updateCard($options) - 更新存储的卡，并非所有网关都支持此方法
deleteCard($options) - 删除存储的卡，并非所有网关都支持此方法

一旦您有了cardReference（可以从响应对象中通过getCardReference获取），您可以在创建收费时使用它代替card参数。

$gateway->purchase(array('amount' => '10.00', 'cardReference' => 'abc'));

在许多情况下，createCard操作也会同时处理初始付款。在这种情况下，您应该在createCard选项中传递'操作'（'authorize'或'purchase'）。

定期计费

在此阶段，此库不包括自动定期支付功能。这是因为每个网关处理定期计费配置文件的方式可能存在很大差异。此外，在大多数情况下，令牌计费将满足您的需求，因为您可以将信用卡存储起来，然后按您喜欢的任何计划进行计费。如果您真的认为这应该是一个核心功能并且值得努力，请随时联系。

传入通知

一些网关（例如Cybersource、GoPay）提供HTTP通知，以通知商户支付完成（或通常状态）。为了帮助处理此类通知，acceptNotification()方法将从HTTP请求中提取交易引用和支付状态，并返回一个通用的NotificationInterface。

$notification = $gateway->acceptNotification();

$notification->getTransactionReference(); // A reference provided by the gateway to represent this transaction
$notification->getTransactionStatus(); // Current status of the transaction, one of NotificationInterface::STATUS_*
$notification->getMessage(); // Additional message, if any, provided by the gateway

// update the status of the corresponding transaction in your database

注意：一些早期的网关使用completeAuthorize和completePurchase消息来处理传入的通知。这些消息正在被转换，complete*消息已弃用。它们不会在OmniPay 2.x中删除，但建议在方便的时候切换到acceptNotification消息。例如，Sage Pay Server completeAuthorize 现在由 acceptNotification 处理。

示例应用程序

在omnipay/example存储库中提供了一个示例应用程序。您可以使用PHP内置的Web服务器（PHP 5.4+）运行它。

$ php composer.phar update --dev
$ php -S localhost:8000

有关更多信息，请参阅Omnipay示例应用程序。

支持

如果您在使用Omnipay时遇到一般性问题，我们建议在Stack Overflow上发帖。务必添加omnipay标签，以便更容易被发现。

如果您想了解发布公告，讨论项目想法或提出更详细的问题，还可以订阅邮件列表。

如果您认为您发现了一个错误，请使用适当软件包的GitHub问题跟踪器报告，或者更好的做法是，分支库并提交一个pull请求。

安全

如果您发现任何与安全相关的问题，请发送电子邮件到[email protected]，而不是使用问题跟踪器。

反馈

请提供反馈！我们希望使这个库尽可能多地用于各个项目中。请前往邮件列表并指出您喜欢和不喜欢的地方，或者分支项目并提出建议。没有问题太小。

league / omnipay

维护者

详细信息