misavan/boipa_php_sdk

支付API的PHP实现

维护者

详细信息

github.com/Misavan/boipa_php_sdk

源代码

问题

安装: 55

依赖项: 0

建议者: 0

安全: 0

星级: 0

关注者: 1

分支: 0

开放问题: 0

1.0.0 2024-04-08 13:06 UTC

Requires

  • php: >=5.6.0
  • ext-curl: *
  • ext-hash: *

Requires (Dev)

GPL-2.0-or-later 88fce854bfb40737c09a7db21f3f8c59637db4d0

  • peter <peter.shang.woop@nodus.com>

This package is auto-updated.

Last update: 2024-09-08 13:59:47 UTC

README

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

快速开始

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

本节将非常快速地介绍如何使用它，并在本文件的稍后部分提供更多详细信息。

开始之前

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

设置您的项目

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

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

Composer是一个流行的依赖管理工具，您可以在https://getcomposer.org.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/ 文件夹下找到各种示例代码。

Payments PHP SDK 参考文档

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

配置 SDK 和其请求对象

SDK 的对象有时具有配置参数，通过这些参数可以控制它们的操作方式。存在一个名为 Payments/Payments 的通用配置类，其中包含适用于所有其他类的通用参数，还有仅控制其他类上特定支付操作的参数 - 例如，每个支付操作对象（或请求对象）也将有自己的参数。

适用于所有对象的参数示例包括 API 网址和认证数据。单个请求参数可以是单个支付交易详情 - 信用卡号和过期日期、订单详情等。

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

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

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

如何配置对象

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

  • 方法调用，如下：
	$myMerchantId = $payments->merchantId();

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

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

这将设置参数的值，覆盖任何以前的设置，并返回 Payments 对象的相同实例，这样您就可以继续设置参数，像 builders 风格。

  • 属性，如下：
	$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规范文档。

典型请求流程

在您的PHP代码中，您最可能创建一个支付对象，配置它，并使用它创建一个或多个请求对象。然后您将设置参数到它们，并调用它们的 execute() 方法将它们实际提交到支付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，因此您可以区分 Payments SDK 和您应用程序代码中的其他错误。

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

V. 处理API响应

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

响应对象也继承自Payments/Configurable类，因此您可以通过与请求对象相同的方式获取API返回的参数（请参见上面的方法）。显然，由于这些对象仅存在于向您的应用程序提供操作结果，因此设置任何参数值都没有任何效果。

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

Payments错误

偶尔您的支付处理API可能无法成功完成请求，并会返回错误。请查看API规范文档，以了解更多关于错误及其原因的信息。

Payments异常

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

类似地 - 当您调用 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 … ;