README

一个紧凑的 PHP 库，用于通过 Barion Smart Gateway 管理在线电子货币和卡支付。
它允许您仅用几行代码即可接受信用卡、电子货币和电汇支付。

此库将帮助您

在多种场景中轻松启动在线支付（即时支付、预约/保证金、延迟扣款、第三方支付、周期性/令牌支付等）
获取指定支付的详细信息
完全或部分完成进行中的预约支付，支持自动退款
完全或部分退款完成的支付交易

只需几行简单的代码即可完成所有操作！

系统要求

PHP 8.2 或更高版本
cURL 模块启用（至少 v7.18.1）
SSL 启用（使用 OpenSSL 且版本至少为 0.9.8f 的系统）

支持旧版本

如果您使用的是 PHP 8.1 或更低版本，请下载我们的库版本 1.4.11。
请注意，在集成过程中使用即将停止支持或已停止支持的软件是不被推荐的。

支持的 API 版本

安装

Composer

您可以通过 Composer 安装此库。运行以下命令

composer require barion/barion-web-php

然后使用 Composer 生成必要的 autoload 文件。
库将自动检测 Composer 生成的 autoload 文件，并使用它们进行自动加载。

手动安装

如果您不想使用 Composer，只需将 barion 库的内容复制到目标文件夹。
如果没有检测到 Composer 生成的文件，库将使用自己的自动加载机制。

注意
确保在运行 PHP 脚本时设置必要的路径访问权限。

基本用法

在您的 PHP 脚本中包含 BarionClient 类

require_once 'library/BarionClient.php';

注意
无论您是否使用了 Composer，BarionClient 都会为您自动加载所有内容。

然后实例化一个 Barion 客户端。为了实现这一点，您必须提供三个关键参数

1. 在 Barion 注册的在线商店的密钥（称为 POSKey）

$myPosKey = "9c165cfccbd1452f830721a3a9cee664";

2. 目标 Barion API 版本号（默认为 2）

$apiVersion = 2;

3. 连接到的环境。这可以是测试/沙箱系统，或生产环境。

// Test environment
$environment = \Barion\Enumerations\BarionEnvironment::Test;

// Production environment
$environment = \Barion\Enumerations\BarionEnvironment::Prod;

使用这些参数，您可以创建一个 BarionClient 类的实例

$BC = new \Barion\BarionClient(
    poskey: $myPosKey,
    version: $apiVersion,
    env: $environment,
    useBundledRootCerts: false
);

注意
如果遇到 SSL 连接问题，请最后将 useBundledRootCerts 设置为 true。您有责任使用包含最新国际受信任 CA 证书链的软件。库的作者不对由于使用库捆绑的证书链而导致的停机负责。

基本流程

使用库管理支付过程分为两个步骤

1. 开始支付

1.1. 创建请求对象

要开始在线支付，您必须创建一个或多个 Payment Transaction 对象，向它们添加交易 Items，然后在 Payment 对象中将这些交易分组。

首先，创建一个 ItemModel

$item = new \Barion\Models\Common\ItemModel();
$item->Name = "TestItem";
$item->Description = "A test product";
$item->Quantity = 1;
$item->Unit = "piece";
$item->UnitPrice = 1000;
$item->ItemTotal = 1000;
$item->SKU = "ITEM-01";

然后创建一个 PaymentTransactionModel，并将上面提到的 Item 添加到其中

$trans = new \Barion\Models\Payment\PaymentTransactionModel();
$trans->POSTransactionId = "TRANS-01";
$trans->Payee = "webshop@example.com";
$trans->Total = 1000;
$trans->Comment = "Test transaction containing the product";
$trans->AddItem($item);

最后，创建一个 PreparePaymentRequestModel，并将上面提到的 PaymentTransactionModel 添加到其中

$ppr = new \Barion\Models\Payment\PreparePaymentRequestModel();
$ppr->GuestCheckout = true;
$ppr->PaymentType = \Barion\Enumerations\PaymentType::Immediate;
$ppr->FundingSources = array(FundingSourceType::All);
$ppr->PaymentRequestId = "PAYMENT-01";
$ppr->PayerHint = "user@example.com";
$ppr->Locale = \Barion\Enumerations\UILocale::EN;
$ppr->OrderNumber = "ORDER-0001";
$ppr->Currency = \Barion\Enumerations\Currency::HUF;
$ppr->RedirectUrl = "https://webshop.example.com/afterpayment";
$ppr->CallbackUrl = "https://webshop.example.com/processpayment";
$ppr->AddTransaction($trans);

注意
用于认证的密钥 POSKey 不是请求对象的一部分。
Barion 客户端类会自动将此值注入到发送到 Barion API 的每个请求中。

1.2. 调用 Barion API

现在，您可以使用刚刚创建的请求模型调用 Barion 客户端的 PreparePayment 方法

$myPayment = $BC->PreparePayment($ppr);

Barion API 现在准备了一个可以被任何人支付的付款实体。

变量 $myPayment 存储了从 Barion API 收到的响应，它是一个 PreparePaymentResponseModel 对象的实例。

1.3. 将用户重定向到 Barion Smart Gateway

您可以使用响应中的 PaymentId 值将用户重定向到 Barion Smart Gateway。您必须在 ID 查询字符串参数中提供此标识符。
完整的重定向 URL 看起来是这样的

https://secure.barion.com/Pay?id=<your_payment_id>

用户现在可以在 Barion Smart Gateway 完成支付。

2. 获取付款信息

在这个例子中，我们将获取上面创建的付款的详细信息。

2.1. 创建请求对象

要请求有关付款的详细信息，您只需要一个参数：付款标识符。这是之前用于重定向用户的 PaymentId。

64157032d3dc4296aedafd4b0994c64e

2.2. 调用 Barion API

要请求付款详情，我们使用上述标识符调用 Barion 客户端类的 PaymentState 方法。

$BC->SetVersion(4);
$paymentDetails = $BC->PaymentState("64157032d3dc4296aedafd4b0994c64e");

注意
PaymentState API 在 API 版本 4 中可用。v2 GetPaymentState API 现已弃用。

根据响应中收到的付款状态和参数，商店现在可以决定付款是否成功。

API 文档

了解 Barion API 在 HTTP 调用期间返回的各种状态和错误的基本知识至关重要。
请参阅官方的 Barion API 文档，了解更多有关各种 API 端点和它们响应的信息。

基本故障排除

以下是一些在联系我们的支持之前可能想要检查的常见错误

1. 在发送我的请求时，我得到 "用户身份验证失败" 错误

检查您是否向正确的环境发送了正确的 POSkey，例如，如果您想调用测试环境中的 API，请使用在测试网站上注册的商店的 POSkey。
检查发送的数据是否实际上是有效的 JSON 字符串，没有任何特殊字符、分隔符、换行符或无效编码。

2. 在测试环境中，我得到 "商店已关闭" 错误消息

登录到 Barion 测试网站后，检查您的商店是否已开启。请注意，您必须填写商店的每一项数据，然后将其发送以供审批。在此之后，审批将自动完成，您的商店将处于“开启”状态。这仅适用于测试环境。

3. 当尝试调用 API 时，我得到有关无效证书的 SSL 错误

请确保双重检查您的服务器证书和发行者的可信状态。务必及时更新服务器证书，以避免服务中断。
检查您架构的每个组件是否有过时的软件。务必尽可能使用最新的 PHP、其他运行时，甚至操作系统。受信任的证书链可能会过期或被吊销，Barion 对此无能为力。强烈不建议使用 End-Of-Support 和 End-Of-Life 软件。
作为最后的手段，您可能需要尝试使用将 useBundledRootCerts 设置为 true 来创建 BarionClient 实例。但请注意，无法保证捆绑的证书链始终有效。

寻求帮助

如果您有任何问题或需要此插件的使用帮助，请加入我们的 Discord 服务器并向开发者社区提问！

许可证

此存储库可在Apache 2.0 许可证下获得。

贡献

如何为 Barion API 库做出贡献

将 barion/barion-php-web 存储库进行分支。
在您的分支中创建一个新的分支，进行所需的更改，然后将更改推送到您的分支。
向 barion/barion-php-web 存储库创建拉取请求。
在拉取请求中，请详细描述您开发的功能或解决的问题。

我们将尽快尝试审查您的拉取请求。

版本历史

2.0.0 2024年7月16日
1.4.11 2024年4月2日
1.4.10 2022年6月13日
1.4.9 2022年6月9日
1.4.8 2022年6月9日
1.4.7 2022年5月25日
1.4.6 2021年4月28日
1.4.5 2021年4月15日
1.4.4 2021年2月17日
1.4.3 2020年12月11日
1.4.2 2019年8月15日。
1.4.1 2019年8月14日。
1.4.0 2019年8月8日。
1.3.2 2019年8月5日。
1.3.1 2019年3月20日。
1.3.0 2019年3月12日。
1.2.9 2017年5月16日。
1.2.8 2017年4月13日。
1.2.7 2017年2月14日。
1.2.5 2016年11月7日。
1.2.4 2016年5月25日。
1.2.3 2016年1月14日。
1.2.2 2016年1月11日。
1.1.0 2015年11月27日。
1.0.1 2015年11月26日。
1.0.0 2015年11月17日。

有关版本变更的详细信息，请参阅changelog.md 文件。

barion / barion-web-php

维护者

详细信息