README

此库提供对 BOIPA Gateway 的集成访问。

快速入门

BOIPA Gateway PHP SDK 是一个小的 PHP 代码库，您可以使用它快速集成到 BOIPA Gateway 系统中，并提交交易、检查状态等。

本节将简要介绍如何使用它，稍后在本文件中您将找到更多详细信息。

开始之前

在使用 BOIPA Gateway PHP SDK 之前，您应该熟悉《商家 API 规范》文档的内容，因为它描述了特定支付交易中所有字段及其含义。

设置项目

BOIPA Gateway PHP SDK 以 composer(*) 包或依赖项的形式提供，您应将其添加到您的 PHP 项目中才能使用它。

完成后 - 所有代码都将对您在 Payments PHP 命名空间下可用。

Composer 是一个流行的依赖管理工具，您可以在 https://composer.php.ac.cn/ 上找到更多关于它的信息。

##选择操作模式

BOIPA Gateway SDK 允许您选择两种使用方式：

服务器到服务器模式 - 在这种模式下，您的 PHP 代码代表用户执行所有必要的准备和操作，但不需要用户直接参与，或者
浏览器到服务器模式 - 在这种模式下，您的网页仅指示客户端的浏览器直接连接到支付处理服务器，其中所有操作都在两者之间直接完成，而无需您的 PHP 代码进一步参与。

选择最适合您项目的模式。

配置

支付 SDK 在执行任何操作之前需要“了解”一些信息 - 例如 - 您的认证凭证；您的商家编号；如果您只是测试您的应用程序并且实际上不想要使用真正的信用卡，或者它正在运行在生产环境中等。

在使用之前，您需要正确配置它。所有配置都是通过 Payments/Payments 类完成的。使用它的最简单方法就是创建一个新的实例，选择其操作环境（测试或生产），然后一次性提供所有其他详细信息，或者一个接一个。例如

测试环境，一次性设置所有配置参数

$payments = (new Payments())->testEnvironment(array(
  ‘merchantId’ => ‘42’, 
  ‘password’ => ‘mypassword’));

生产环境，逐一设置参数

$payments = (new Payments())->productionEnvironment()->
  merchantId(‘42’)->
  password(‘mypassword’);

有关设置和获取参数的更多详细信息，请参阅下文。

如果您需要更改配置设置，例如生产 URL 或其他内容，您可以遵循以下两种情况中的任何一种

对于永久更改，请编辑 lib/PaymentsConfig.php 并修改那里的静态变量，以便任何使用库的操作都将使用它们，或者
对于临时更改，您可以通过设置 Config 类的静态参数的值来完成。

例如

Config::$ProductionUrls["SessionTokenRequestUrl"] = Some.url;

然后当您调用

$payments = (new Payments())->productionEnvironment()->
merchantId(‘42’)->
password(‘mypassword’);

它将采用新设置的 SessionTokenRequestUrl。

发出请求

使用您刚刚配置的 Payments 对象创建支付处理请求，例如捕获、购买、状态检查、退款等。

	$newPurchase = $payments->purchase();

所有请求对象都继承自 Payments/Executable 类，并且它们也有可能需要设置的配置参数。您可以像处理 Payments 对象一样执行此操作。您可以批量执行

$newPurchase = $payments->purchase(array(
  ‘number’ => ‘42’,
  ‘nameOnCard’ => ‘Alice’,
  …));

或者逐个

	$newPurchase = $payments->purchase()->
		number(‘42’)->
		nameOnCard(‘Alice’)->
..<and so on>;

请参考商家API规范文档，获取各个字段的详细规范。

执行和处理响应

最后，一旦你有了请求，你可以通过调用它的execute()方法来执行它。你可以给它一个回调（一个PHP可调用对象），该回调将处理返回的数据。

try {
		$myRequest->execute(function($res) {
			// do something with $res
		});
	} catch(Payments/PaymentsException e) {
	// something went wrong, did you configure your request properly?
}

或者你可以将结果分配给你选择的变量

	try {
		$res = $myRequest->execute();
		// do something with $res
	} catch(Payments/PaymentsException e) {
		// something went wrong, did you configure your request properly?
	}

关于结果数据的更多信息，请参考商家API规范文档。

查看一些示例

你可以在SDK的examples/文件夹中找到各种示例，示例代码为PHP。

支付PHP SDK参考

在本节中，你可以找到关于SDK的更多详细信息。

配置SDK及其请求对象

SDK的对象有时通过其配置参数来控制它们的操作方式。存在一个通用的配置类，称为 Payments/Payments，它包含适用于所有其他类的通用参数，还有一些参数仅控制其他类上设置的个别支付操作 - 例如，每个支付操作对象（或请求对象）都有自己的参数。

适用于所有对象的参数示例是API URL和认证数据。个别请求参数可以是单个支付交易详情，例如信用卡号和到期日期、订单详情等。

配置参数可能是必需的，即如果未设置这些参数，则操作将失败，条件性的或可选的。

你可以在商家API规范文档中找到完整的参数列表。

所有可配置的类都是Payments/Configurable类的子类。

如何配置对象

Payments/Configurable的实例持有一组参数 -> 值映射，这些映射以三种方式公开 - 作为方法、作为属性或作为数组索引。方法或属性名称和数组索引值确定在给定操作中要使用哪个参数。也就是说，你可以按以下方式访问对象 Payments 的参数 merchantId：

方法调用，如下所示

	$myMerchantId = $payments->merchantId();

这将返回参数的当前值，并且

	$samePaymentsObject = $payments->password(‘myPassword’);

这将设置参数的值，覆盖任何以前的设置，并返回 Payments 对象的相同实例，以便你可以在其上继续设置参数，builder 风格。

属性，如下所示

	$currentPaymentAmount = $paymentRequest->$amount;

它给你参数的当前值，并且

	$paymentRequest->$amount = ‘42.00’;

它设置值，覆盖可能存在的任何以前的设置。

数组索引，如下所示

	$transactionToRefund = $refundRequest[‘originalMerchantTxId’];

它给你当前的设置，并且

	$refundRequest[‘originalMerchantTxId’] = 42;

设置并覆盖参数。

有时你可能有所有设置都已在另一个对象或数组中（例如，当你从数据库或配置文件中检索它们时），并且你可能希望一次性设置所有参数。而不是迭代它们，你可以使用批量设置，通过

将数组或Iterator对象传递给构造函数，如下所示

	$payments = new Payments($myConfigOpts);
	$refundRequest = $payments->refund($myRefundOpts);

注意：请求对象是通过调用它们各自的 Payments 方法创建的，而不是通过构造函数。

将对象作为函数调用并传递数组或Iterator，如下所示

	$refundRequest = $payments->refund();
	$refundRequest($myRefundOpts);

使用一些特殊的辅助方法，如下所示

	$payments = new Payments();
	$paymentsTest = $payments->testEnvironment($myConfigOpts);
	$paymentsProduction = $payments->productionEnvironment($myConfigOpts);

设置和获取参数值的所有方法都可以完全互换使用 - 你可以在单个对象上使用任何组合，其结果将与你可以使用的任何其他组合完全相同。

检查一个参数是否已被分配了值就像使用PHP自带的函数一样简单 - isset()，array_key_exists()等等。

通用配置参数

通用配置参数是指你在支付对象上配置的参数，然后它们将适用于你从该对象获取的所有后续请求对象。理想情况下，你只需要在创建主支付对象时配置一次，然后就可以避免重复设置它们。

注意

这些参数不是全局的 - 如果你创建了一个请求对象，它将保留创建支付对象时的配置。支付对象的进一步更改不会影响已经创建的请求对象。

注意

支付对象有两个特殊的辅助方法来设置预定义的参数列表，具体取决于你的环境选择 - testEnvironment()和productionEnvironment()（见上文了解如何使用它们）。你必须使用其中一个，否则你的配置将不完整。

要获取支持的参数列表及其含义的完整信息，请参阅商户API规范文档。

支付请求、结果及其参数

每次支付操作都有自己的请求对象。要成功执行任何请求，需要创建相关对象，配置它，然后调用其execute()方法。

总共有7个请求对象类

Payments/Tokenize将卡标记为未来使用。
Payments/Auth请求支付授权。
Payments/Capture对已授权的支付执行捕获操作。
Payments/Void取消之前已授权的支付。
Payments/Purchase一次执行授权和捕获操作（且不能取消）。它还支持定期支付(COF) - 将cardOnFileType设置为'First'进行初始交易，将cardOnFileType设置为'Repeat'并将cardOnFileInitiator设置为'Merchant'进行后续交易。
Payments/Refund对之前的捕获操作进行部分或全部退款。
Payments/StatusCheck返回已发行的支付交易的状态，因此它实际上不会生成新的交易。

所有类都是Payments/Request类的后代，并从创建它们的Payments对象继承设置。

有关支付交易的信息，请参阅[商户API规范](docs/0 - BOIPA Gateway - 0 - Overview.pdf)文档。

典型请求流程

在你的PHP代码中，你很可能会创建一个支付对象，配置它，并使用它创建一个或多个请求对象。然后，你将设置参数并将它们提交给 Payments API，实际提交它们。然后，它将返回你需要使你的应用正常工作所需的数据 - 这些可能是由于配置错误、意外条件、稍后需要的交易详情等错误。

I. 首先创建并配置一个支付对象

	$payments = (new Payments())->productionEnvironment($myConfigOptions);

(有关配置参数的更多详细信息，请见上文)。

II. 从新创建的对象创建你的请求并设置一些配置选项

	$myAuth = $payments->auth($myAuthOptions);

	$myCapture = $payments->capture($myCaptureOptions);

	$myVoid = $payments->void($myVoidOptions);

	$myPurchase = $payments->purchase($myPurchaseOptions);

	$myRefund = $payments->refund($myRefundOptions);

	$myStatusCheck = $payments->statusCheck($myStatusCheckOptions);

(有关配置对象的其他方法以及每个请求的单独参数名称，请见上文)

III. 然后发出请求并将方法调用结果分配给变量或提供一个PHP可调用的回调

	try {
		// without a callback
		$myPurchaseResult = $myPurchase->execute();

		// or with a callback
		$myPuchase->execute(function($res) {
			// do something here
		});
} catch(Payments/Exception e) {
	// don’t forget to check for errors!
}

IV. 注意异常

有时SDK无法执行你的请求，它将抛出异常。这可能是由于配置错误或没有连接到API等意外条件。这样的异常总是继承自Payments/Exception，因此你可以区分支付SDK和其他应用代码的错误。

异常将在本文件的稍后部分详细介绍。

V. 处理API响应

无论您如何发出请求，您都会收到一个包含 Payments API 返回参数的 Payments/Response 类的实例。此外，根据操作的成功与否，它也可能是 Payments/Success 的实例，如果操作成功，Payments/Error 如果 API 返回了错误或 Payments/Info。您可以使用 instanceof 运算符来快速判断是否存在失败。

响应对象也继承了 Payments/Configurable 类，因此您可以像请求对象一样获取 API 返回的参数（参见上方了解如何实现）。显然，这些对象仅用于向您的应用程序提供操作结果 - 在它们上面设置任何参数值都没有效果。

每个请求都将返回其各自的响应参数。例如，一个 Capture 请求将提供的参数之一是它捕获的金额。这些参数在 API Specification for Merchants 文档中有描述。

支付错误

有时您的支付处理 API 无法成功完成请求，并会返回错误。请查阅 API Specification for Merchants 文档以了解有关错误及其发生原因的更多信息。

支付异常

除了在请求处理过程中发现的错误之外，还可能抛出异常。以下是 Payments PHP SDK 异常列表：

Payments/ConfigurationEndpointNotSet 由于 API 端点尚未配置而抛出，通常由没有调用 testEnvironment() 或 productionEnvironment() 而引起。
Payments/ExecuteNetworkError SDK 无法连接到 API 或存在其他网络连接相关错误。
Payments/MethodNotFound 当您尝试实例化一个不存在于 Payments 请求中的请求对象时抛出。
Payments/ParamNotSet 当一个必需的参数未设置时抛出。
Payments/ProcessDataNotSet 由于使用未配置的对象而引起。

所有这些类都继承自一个基本的 Payments/Exception 类，这样您就可以在 try-catch 块中轻松地将它们区分开来。

高级使用场景

本节包含了一些可能对您节省工作或使您的应用程序代码更简洁有帮助的建议和想法。

您不应将它们视为正确使用 Payments PHP SDK 的方式，因为它们只是建议。

通用参数与个别配置参数

Payments PHP SDK 及其 Configurable 对象在设置参数方面非常灵活。在可以设置特定参数的地方几乎没有限制。因此，请使用 Payments 对象设置将在后续请求中共享的参数，如商户 ID、密码或几乎所有其他内容。

这可能会使您的代码更短、更简单。

使用您应用程序的对象

通常情况下，您的应用程序可能已经使用其他类和对象，例如数据库结果对象（如 mysqli_result）或业务逻辑对象（如订单、产品、商户等）。

如果这些实现了任何 PHP 类似迭代器的接口，例如 mysqli_result，则可以使用它们直接配置 Payments PHP SDK，因为 SDK 可以在批量设置操作中接受它们。

以类似的方式，当您 execute() 请求时，您传入一个回调，该回调将处理结果，而这个回调可能只是您已经开发的一个类似 Payment 的对象中的方法。这样，您的业务逻辑就不会分散在各种源文件中。

使用构建者模式来编写更少的代码

构建者模式是一种常用的处理对象的方式，这些对象在可使用之前需要执行一系列的方法调用，这正是配置 Payments PHP SDK 对象的情况。如果你已经选择了方法调用，那么只需将它们依次“链式”调用，参数设置方法总是返回 $this

$myObject = $myObject->
myParamA(‘valueA’)->
myParamB(‘valueB’)->
myParamC(‘valueC’)->
myParamD(‘valueD’)->
… and so on for as long as you like … ;

subhoalmighty / boipa_gateway_php_sd

维护者

详细信息