README

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

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

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

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

长话短说

只想看看一些代码吗？

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`。

安装

composer require league/omnipay:^3 omnipay/paypal

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

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

从v2升级到v3

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

如果没有v3版本，请提出问题或自己升级网关并创建一个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 对象。

可以使用 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() - 将来自离线网关的传入请求转换为用于进一步处理的通用通知对象

现场网关不需要实现 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

此外，大多数网关将覆盖响应对象，并提供访问网关返回的任何额外字段。

重定向响应

重定向响应根据客户浏览器是否必须使用 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选项中传递“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问题跟踪器报告它，或者更好的是，fork库并提交一个pull请求。

安全

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

反馈

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

muhammadaldan / omnipay8

维护者

详细信息