aiandev/boipa_php_sdk

该软件包最新版本(1.0.0)没有提供许可证信息。

PHP实现支付API

该软件包的规范仓库似乎已不存在,因此该软件包已被冻结。

1.0.0 2020-11-14 22:04 UTC

This package is auto-updated.

Last update: 2024-02-15 06:03:39 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/文件夹下找到各种PHP代码示例。

Payments PHP SDK参考

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

配置SDK及其请求对象

SDK的对象有时有自己的配置参数,通过这些参数您可以控制它们的工作方式。有一个名为Payments/Payments的一般配置类,其中包含适用于所有其他类的通用参数,还有仅控制其他类上的单个支付操作的参数 - 例如,每个支付操作对象(或请求对象)都有自己的参数。

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

配置参数可能是必需的,即 - 如果未设置,则操作将失败,条件性可选的

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

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

如何配置对象

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

  • 方法调用,例如
	$myMerchantId = $payments->merchantId(); 

这将返回参数的当前值,并

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

这将设置参数的值,覆盖任何以前的设置,并返回相同的 Payments 对象实例,以便您可以继续设置其上的参数,构建器样式。

  • 一个属性,例如
	$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规范 文档。

典型请求流程

在您的PHP代码中,您很可能会创建一个Payments对象,对其进行配置,并使用它创建一个或多个Requests对象。然后您将设置参数并调用它们的 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 和应用程序代码中的其他错误。

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

V. 处理API响应

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

响应对象也继承自 Payments/Configurable 类,因此您可以通过与请求对象相同的方式获取API返回的参数(参见上面的操作方式)。显然,由于这些对象仅用于向您的应用程序提供操作结果,因此设置任何参数值都不会产生影响。

每个请求都会返回其单独的响应参数。例如,Capture 请求会提供给您捕获的金额。这些参数在 商家API规范 文档中有详细描述。

支付错误

有时您的支付处理API无法成功完成请求,并将返回错误。请查看 商家API规范 文档以了解更多关于错误及其原因的信息。

支付异常

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

  • 支付/配置端点未设置 抛出此异常是因为API端点尚未配置,通常是由于未调用 testEnvironment()productionEnvironment() 造成的。
  • 支付/执行网络错误 SDK无法连接到API或存在其他网络连接相关错误。
  • 支付/方法未找到 当您尝试实例化一个不存在于支付请求中的请求对象时抛出。
  • 支付/参数未设置 当必填参数未设置时抛出。
  • 支付/处理数据未设置 由于使用未配置的对象引起。

所有这些类都继承自基础支付/异常类,这样您可以轻松地在try-catch块中区分它们。

高级使用场景

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

您不应将它们视为使用支付PHP SDK的正确方式,因为它们不过是建议而已。

通用参数与单个配置参数

支付PHP SDK及其Configurable对象在设置参数方面非常灵活。几乎在您想设置给定参数的地方都没有限制。因此,请使用Payment对象设置将在后续请求中共享的参数,例如商户ID、密码或其他任何东西。

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

使用您应用程序的对象

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

如果这些实现了任何类似迭代器的PHP接口,比如mysqli_result那样,那么您可以直接使用它们来配置支付PHP SDK,因为它可以接受批量设置操作。

以类似的方式 - 当您执行请求时,您传递一个回调,其中将处理结果,而这个回调可能正是您已经开发的一个类似支付的对象中的方法。这样,您的业务逻辑就不会分散在各个源文件中。

使用Builder模式以减少代码量

Builder模式是处理需要在它们可用之前进行长序列方法调用才能使用的对象的常用方式,这正是配置支付PHP SDK对象的情况。如果您已选择方法调用,那么只需“连锁”它们一个接一个,参数设置方法总是返回$this

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