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版本，请提交一个问题或自行升级网关并创建PR。请参阅omnipay/common升级指南

注意：v3版本的包名已从omnipay/omnipay更改为league/omnipay

支付网关

所有支付网关都必须实现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对象。

可以使用getter和setter访问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 - 获取可用于未来付款的卡引用。例如，这可以用于每月计费场景。

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

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

• 卡片
• 令牌
• 金额
• 货币
• 描述
• 交易ID
• 客户端IP
• 返回URL
• 取消URL

将选项以如下方式传递给方法

$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() 来测试响应是否成功。如果与网关通信出现错误，或者您的请求明显无效，将会抛出异常。一般来说，如果网关没有抛出异常，但返回了不成功的响应，那么您应该将此消息显示给客户。如果抛出了异常，那么可能是您的代码中存在bug（缺少必填字段），或者与网关的通信出现错误。

您可以通过将整个请求包裹在 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 选项中传递 'action'（'authorize' 或 'purchase'）。

周期性计费

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

入站通知

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

安全

如果您发现任何与安全相关的问题，请通过电子邮件barryvdh@gmail.com报告，而不是使用问题跟踪器。

反馈

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