README

实时聊天： ![Gitter](https://badges.gitter.im/Join Chat.svg)

本模块的目的是让开发者能够轻松地将在线支付功能添加到他们的SilverStripe应用程序中。简单来说，它封装了PHP Omnipay支付库，并提供了一些额外的功能。要了解更多关于omnipay的信息，请参阅：https://github.com/thephpleague/omnipay

版本

3.0+适用于SilverStripe 4

对于2.x（与SS 3.x兼容）的贡献，请使用2分支。

要求

silverstripe框架 4+
omnipay 3及其依赖项（包括guzzle和一些symphony库）。

功能

通过YAML配置进行网关配置。
处理支付/事务模型。
在数据库中提供详细和结构化的日志。
为访客提供一个或多个网关进行选择。
提供可按网关变化的表单字段。
支持不同类型的网关：站内捕获、站外捕获和手动支付。
封装Omnipay php库。
支持多种货币。

兼容的支付网关

有许多可用的网关，您可以选择单独安装。

在Packagist上搜索很有用：https://packagist.org.cn/search/?q=omnipay

如果需要，编写自己的网关集成也不太困难。

安装

目前，使用Composer是设置此模块的唯一支持方式

composer require silverstripe/silverstripe-omnipay ^3@dev

从版本2.0开始，此模块仅需要omnipay/common，因此您还需要拉取您选择的支付适配器。请参阅http://omnipay.thephpleague.com/gateways/official/，其中第二列是包名称。

例如，如果您的网站使用PayPal，您还需要运行

composer require omnipay/paypal

此外，还有如何启用手动支付或PayPal Express的简要指南。

配置

Silverstripe Omnipay提供许多配置选项。完整的列表可以在我们的专用配置文档中找到。

网关命名规范

网关的命名方式由Omnipay模块决定。由于一个Omnipay-Payment-Driver中可能存在不同的网关，我们需要一种方法通过不同的名称来标识这些网关。

规则非常简单：以命名空间标记符（\）开头的类名保持不变。非命名空间类预计位于\Omnipay命名空间中。在非命名空间类中，下划线或斜杠（\）用于表示特定的网关实例。

示例

\Custom\Gateway → \Custom\Gateway
\Custom_Gateway → \Custom_Gateway
Stripe → \Omnipay\Stripe\Gateway
PayPal\Express → \Omnipay\PayPal\ExpressGateway
PayPal_Express → \Omnipay\PayPal\ExpressGateway

另一个示例：[Omnipay PayPal](https://github.com/thephpleague/omnipay-paypal)提供了三种不同的网关实现：ExpressGateway、ProGateway和RestGateway。这些网关的名称将是：PayPal_Express、PayPal_Pro和PayPal_Rest。

请遵循上述规则，在您的配置文件中选择正确的网关名称。

在本模块的文档和示例中，您会发现使用下划线的语法。它比使用命名空间标记符（\）的语法更容易阅读且更不易出错（转义）。

用法

我们在文档页面中制作了一个全面的入门指南。

支付服务和服务工厂

目前有五种支付服务可用，它们映射到Omnipay公开的方法。您可以在实践中使用哪种服务取决于单个网关的功能。一些网关将支持所有服务，而另一些网关只支持少数服务（例如，“手动”网关不支持“购买”）。

服务包括：

PurchaseService：直接购买/捕获金额。
AuthorizeService：授权金额。
CaptureService：捕获之前授权的金额。
RefundService：退还之前捕获的金额。
VoidService：取消/撤销已授权的支付。

这些服务中的每一个都实现了initiate和complete方法。始终需要initiate方法来启动服务。根据网关如何处理请求，您可能还需要complete方法。

这是离线支付表单的情况，其中initiate将用户重定向到支付表单，一旦他从离线表单返回，就会调用complete来最终确定支付。

另一个（较少见）的情况是，当支付提供者使用异步通知来确认支付更改时。

虽然您可以显式实例化服务，但建议使用ServiceFactory。服务工厂允许轻松自定义针对哪些意图实例化哪些类。服务工厂还可以根据为所选网关配置的内容自动返回AuthorizeService或PurchaseService。

以下常量可用于实例化服务：

INTENT_PURCHASE请求购买服务。
INTENT_AUTHORIZE请求授权服务。
INTENT_CAPTURE请求捕获服务。
INTENT_REFUND请求退款服务。
INTENT_VOID请求空服务。
INTENT_PAYMENT根据所选网关返回授权服务或购买服务。

代码示例

$payment = Payment::create()->init("PxPayGateway", 100, "NZD");

// The service will be a `PurchaseService`
$service = ServiceFactory::create()->getService($payment, ServiceFactory::INTENT_PURCHASE);

// Initiate the payment
$response = $service->initiate($data);

将正确数据传递给购买函数

OmniPay库有一个定义好的参数集合，需要在调用时传入。以下是您应该将数据映射到的参数列表：

transactionId
firstName
lastName
email
company
billingAddress1
billingAddress2
billingCity
billingPostcode
billingState
billingCountry
billingPhone
shippingAddress1
shippingAddress2
shippingCity
shippingPostcode
shippingState
shippingCountry
shippingPhone

注意： transactionId可以是一个标识您所支付事项的参考，例如订单参考ID。它通常出现在银行对账单上，但最终取决于网关如何使用它。

安全性

在自定义支付流程时（例如，通过子类化PaymentForm或OrderProcessor），请注意仅将白名单内的用户输入传递给PurchaseService和底层的OmniPay网关。确保无法注入任意数据的最简单方法是通过使用Form->getData()而不是直接访问$_REQUEST，因为这将仅返回在表单中原始定义的字段的数据。

调试支付

请阅读有关如何设置日志记录的日志记录文档。

重命名网关和翻译

您可以使用翻译系统更改前端可见的网关名称。网关名称必须与您在allowed_gateways YAML配置中输入的相匹配。

例如，在mysite/lang/en.yml内部：

en:
  Gateway:
    Paystation_Hosted: "Credit Card"
    PayPal_Express: "PayPal"

此方法也可以用来提供不同的翻译。有关模块翻译的更多信息，请阅读docs/en/Translating.md

burnbright / silverstripe-omnipay

维护者

详细信息