README

此库提供了对BOIPA网关的集成访问。

快速开始

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

本节将简要介绍如何使用它，在本文档的后面部分，您将找到更多详细信息。

开始之前

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

设置您的项目

BOIPA网关PHP SDK以composer(*)包的形式提供，您应该将其添加到PHP项目中以使用它。

完成此操作后，所有代码都将可供您在 Payments PHP 命名空间下使用。

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

##选择操作模式

BOIPA网关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()等等。

通用配置参数

通用配置参数是在 Payments 对象上配置的参数，然后适用于从该对象获取的所有后续请求对象。理想情况下，你只需在创建主 Payments 对象时配置一次，就可以节省重复设置它们的额外代码。

注意

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

注意

Payments 对象有两个特殊的辅助方法，根据你的环境选择设置预定义参数列表 - 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 对象，配置它，并使用它创建一个或多个请求对象。然后你将设置参数到它们中，并调用它们的 execute() 方法以将其提交给 Payments API。反过来，它将返回你需要的用于使你的应用程序正常工作的数据 - 这可以是由于配置错误、意外条件、稍后需要的交易详情等等。

I. 首先创建和配置一个 Payments 对象

	$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将无法执行你的请求，并抛出Exception。这可能是由于配置错误或无法连接到API等意外条件。此类异常总是继承自Payments/Exception，因此你可以区分 Payments SDK 和其他应用程序代码的错误。

异常的详细描述将在本文件的后续部分进行说明。

处理API响应

无论您如何发出请求，您都将获得一个包含支付API返回参数的 Payments/Response 类的实例。此外，根据操作的成败，它还可能是 Payments/Success 的实例，如果是成功的，或者是 Payments/Error 如果API返回了错误或 Payments/Info 。您可以使用 instanceof 操作符快速检查是否存在失败。

响应对象也继承了 Payments/Configurable 类，因此您可以使用与请求对象相同的方式获取API返回的参数（有关如何实现此操作的说明，请参阅上文）。显然，由于这些对象仅存在于为您的应用程序提供操作结果，因此在它们上设置任何参数值都不会产生任何影响。

每个请求都将返回其特定的响应参数。例如，一个 Capture 请求将为您提供捕获的金额。这些参数在商户API规范文档中进行了描述。

支付错误

有时您的支付处理API可能无法成功完成请求，并返回一个错误。请查看商户API规范文档，了解更多有关错误及其原因的信息。

支付异常

除了在请求处理过程中发现的错误之外，还可能会抛出异常。以下是 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，因为它可以接受批量设置操作。

以类似的方式 - 当你执行一个请求并传入一个回调来处理结果时，这个回调可以是你在已经开发的类似Payment对象中的方法。这样，你的业务逻辑就不会分散在各种源文件中。

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

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

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

quaidesbalises / boipa_sdk

维护者

详细信息