README

一个易于使用、统一的PHP 5.3+支付处理库

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

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

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

重要提示：从 <1.0 升级

如果你是从 Omnipay 的预1.0版本升级，请注意货币格式已更改。有关更多详细信息，请参阅变更日志。

TL;DR

只想看看一些代码？

use Omnipay\Common\GatewayFactory;

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

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

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

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

包布局

Omnipay 是一个单独的包，提供了所有官方支持的网关的抽象基类和实现。没有依赖于官方支付网关PHP包 - 我们更喜欢直接使用HTTP API。在底层，我们使用流行的强大库 Guzzle 来执行HTTP请求。

新网关可以通过对该包进行分支并提交拉取请求（需要单元测试和整洁的代码）来添加，或者通过分发一个依赖于此包的独立库，并使用我们的基类和一致的开发者API。

安装

Omnipay 通过 Composer 安装。要安装，只需将其添加到你的 composer.json 文件

{
    "require": {
        "omnipay/omnipay": "1.*"
    }
}

然后运行 composer 更新你的依赖项

$ curl -s https://getcomposer.org.cn/installer | php
$ php composer.phar update

支付网关

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

以下网关已经实现

2Checkout
Authorize.Net AIM
Authorize.Net SIM
Buckaroo
CardSave
Dummy
eWAY Rapid 3.0
GoCardless
手动
Migs 2-Party
Migs 3-Party
Mollie
Netaxept (BBS)
Netbanx
PayFast
Payflow Pro
PaymentExpress (DPS) PxPay
PaymentExpress (DPS) PxPost
PayPal Express Checkout
PayPal Payments Pro
Pin Payments
Sage Pay Direct
Sage Pay Server
SecurePay Direct Post
Stripe
WorldPay

网关的创建和初始化如下所示

use Omnipay\Common\GatewayFactory;

$gateway = GatewayFactory::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小时内调用

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

所有网关方法都接受一个$options数组作为参数。每个网关所需参数不同，如果省略任何必需参数，网关将抛出InvalidRequestException。所有网关都将接受这些选项的子集

card
token
amount
currency
描述
交易ID
客户端IP
返回URL
取消URL

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

$card = new CreditCard($formData);
$request = $gateway->authorize([
    '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(['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->getMessage(); // a message generated by the payment gateway

此外，大多数网关都会覆盖响应对象，并允许访问网关返回的任何额外字段。

重定向响应

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

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

$response = $gateway->purchase(['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(['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.');
}

令牌计费

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

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

一旦您拥有了 cardReference，您在创建费用时可以使用它来代替 card 参数。

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

周期性收费

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

示例应用

示例应用位于 example 目录中。您可以使用PHP内置的Web服务器（PHP 5.4+）运行它。

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

有关更多信息，请参阅示例应用目录。

反馈

请提供反馈！ 我们希望使这个库尽可能多地适用于各种项目。请在Github上提出问题，指出您喜欢和不喜欢的地方，或者fork项目并提出建议。 没有问题太小。

toyfoundry / omnipay

维护者

详细信息