README

实时聊天: 

本模块的目标是为开发者简化将在线支付集成到 SilverStripe 应用程序的过程。简单来说，它包装了 PHP Omnipay 支付库并提供了一些额外的功能。要了解更多关于 Omnipay 的信息，请参阅：https://github.com/thephpleague/omnipay

要求

• PHP 8.1+
• silverstripe 框架 v5+
• omnipay 3 及其依赖项 - 包括 guzzle 和一些 symphony 库。

功能

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

兼容的支付网关

有众多可用的 网关，您可以单独安装。

使用 packagist 进行搜索很有用：https://packagist.org.cn/search/?q=omnipay

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

安装

目前，仅支持使用 Composer 来设置此模块

composer require silverstripe/silverstripe-omnipay ^3@dev

您还需要引入您选择的支付适配器。请参阅 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 包含三个不同的网关实现：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"

这种方法也可以用来提供不同的翻译。有关模块翻译的更多信息，请参阅文档/en/Translating.md

进一步文档

https://github.com/silverstripe/silverstripe-omnipay/blob/master/docs/en/index.md