README

KeksPHP 是 KEKS Pay API 网上商店后端集成在 PHP 中的实现。您可以在构建自己的自定义实现时将其用作参考，并且它作为库在 Composer/Packagist 上也可用。

它是免费和开源的，并发布在 MIT 许可下。然而，它不是由 KEKS Pay 团队构建或支持的，我无法对其提供任何保证。您可以根据自己的意愿使用它，但您对它的使用完全负责。

KeksPHP 仅处理与 KEKS Pay 的通信。您仍需要将其集成到自己的订单管理中，您还需要实现某种交易日志记录（KeksPHP 使其变得相对容易），并且您还需要为 KEKS Pay 支付构建前端。

要开始与 KEKS Pay 集成，您首先需要联系 KEKS Pay 团队。您可以在 KEKS Pay 网站上找到他们的联系信息以及他们的官方文档。

用法

安装和自动加载

使用 Composer（或其他您选择的工具）安装 KeksPHP。如果您使用 Composer，则所有 KeksPHP 类在包含 autoload.php 后都将可在 KeksPHP 命名空间下访问。

如果您是 Composer 新手，请查看如何使用它，然后回来这里。您也可以直接下载此代码并将其集成到您的项目中（但请确保您也处理了 此项目 的依赖），但 Composer 将使所有这些变得更加容易。

如果您真的想避免使用 Composer，请确保使用 PSR-4 在 src\ 文件夹下使用命名空间 KeksPHP 自动加载类。

要求

KeksPHP 在 PHP 8 下进行了测试。虽然它可能在之前的 PHP 版本下工作，但我无法支持旧版本。

您需要 PHP JSON 和 OpenSSL 扩展。如果您使用 KeksRefund::sumbitRefund 方法，您还需要确保您能够使用 Guzzle。如果您使用 Composer，Guzzle 将自动安装。

设置 KeksSeller

所有其他 KeksPHP 类都需要 KeksSeller 作为成员。

KeksSeller 包含您的 KEKS Pay 配置（CID、TID、API Base 和 Deep Link Base，您将从 KEKS Pay 团队获得）并允许您提供函数来定义如何验证从 KEKS Pay 收到的 advice 以及如何为顾客构建成功/失败 URL。

要设置 CID 和 TID，分别设置类实例的 cid 和 tid 成员。要设置 hashKey，请使用 setHashKey 方法。

$KeksSeller = new \KeksPHP\KeksSeller;
$KeksSeller->cid = "C00111";
$KeksSeller->tid = "P00222";
$KeksSeller->setHashKey("SOMEHASHKEYPROVIDEDBYKEKS");

在生产环境中，您还需要将 API base 和 deep link base 更改为 KEKS Pay 团队提供的值。

如果您的成功和失败 URL 对于每个交易都是固定的，您可以分别设置类实例的 successRedirect 和 failRedirect 成员，如下所示

$KeksSeller->successRedirect = 'https://google.com';
$KeksSeller->failRedirect = 'https://bing.com';

如果它们可以根据交易数据更改，提供闭包如下

$KeksSeller->provideSuccessRedirectFunction(function($KeksTransaction){
	// your code here
	return $successURL;
});

$KeksSeller->provideFailRedirectFunction(function($KeksTransaction){
	// your code here
	return $failURL;
});

闭包将使用相应的 KeksTransaction 类实例调用。

您还需要使用一个函数来验证收到的建议。至少，您需要检查您商店中的购物车金额是否与通过KEKS Pay支付的金额相符。为了让KeksPHP知道调用哪个函数，可以设置一个闭包，如下所示，它将使用从KEKS Pay收到的JSON构建的\stdClass（一个通用对象）实例调用

$KeksSeller->provideValidateAdviceFunction(function($KeksAdvice){
	// your code here, with a very very simple example as well
	// if the JSON has a someField object, you can access it using $KeksAdvice->someField
	if($KeksAdvice->amount != $YourShopOrder->amount) return false;
	return true;
});

如果应接受交易，则返回true。否则，返回false。

KeksTransaction：启动交易

要启动交易，您需要向桌面上的客户提供二维码，向手机上的客户提供深度链接。

为了简化生成这些二维码和深度链接的过程，KeksPHP提供了一个方法来为您构建二维码和深度链接。

为此，通过使用您的KeksSeller实例作为参数来调用构造函数，创建一个KeksTransaction类的实例。

将KeksTransaction实例的bill_id成员设置为您的商店后端中唯一的订单标识符（订单ID、UUID等——KeksPHP不在乎，但您需要能够根据其bill_id识别出订单）。

将KeksTransaction实例的amount成员设置为您想通过KEKS Pay收取的金额。amount是一个int或float，将被KeksPHP适当地格式化。例如，要收取20 HRK，将amount设置为等于20，要收取20.05 HRK，将amount设置为等于20.05——不要将amount设置为格式化的字符串。

然后，调用KeksTransaction实例的buildDeepLinkAndQR方法。这将返回一个包含两个成员的\stdClass实例：qr和deeplink。

$KeksTransaction = new \KeksPHP\KeksTransaction($KeksSeller); // create a new KeksTransaction
$KeksTransaction->bill_id = 20;
$KeksTransaction->amount = 500;
var_dump($KeksTransaction->buildDeepLinkAndQR()); // use $KeksTransaction->buildDeepLinkAndQR()->deeplink to get the deeplink

然后，您可以生成一个包含类中qr成员的值或指向类中deeplink成员的值的链接的二维码，并将其显示给用户。您如何处理这一点：由您决定。

建议您为您的语言（或JavaScript库或API）找到一个库来生成二维码，并使用媒体查询切换二维码/深度链接的可见性。

KeksTransaction：解释收到的建议

要求

您需要构建一个端点，KEKS Pay将向其发送POST请求以发送advice。您还需要在那里实施一些身份验证——KeksPHP不会为您这样做。

您可以通过两种方式来做这件事：使用令牌身份验证和PHP基本认证。

如果您将要自行捕获KEKS Pay请求，请将其存储在一个变量中，并将其作为参数传递给KeksTransaction类的buildFromAdvice方法。如果不这样做，KeksPHP将尝试自行捕获请求。

解释建议

如果您已自行捕获建议内容从php://input

$KeksTransaction = new \KeksPHP\KeksTransaction($KeksSeller);

$Response = $KeksTransaction->buildFromAdvice($YourAdvice);

echo json_encode($Response);

如果您希望KeksPHP为您捕获建议

$KeksTransaction = new \KeksPHP\KeksTransaction($KeksSeller);

$Response = $KeksTransaction->buildFromAdvice();

echo json_encode($Response);

KeksPHP现在将

检查您的TID在KeksSeller中是否与收到的建议中的TID匹配
检查交易是否已清算（状态==0）
调用您的验证闭包，传递收到的建议

如果这些检查中的任何一个失败，KeksPHP将抛出一个KeksIntegrationException，处理它并将它记录在KeksTransactions实例的handledExceptions成员数组中，您可以使用getExceptions方法来检查出了什么问题。

此外，buildFromAdvice方法将返回一个状态为-1且消息等于异常消息的响应。

如果这些检查通过，KeksPHP将返回一个状态为0且消息为'Accepted'的响应。

响应KEKS Pay

处理交易后响应 KEKS 支付，请将 buildFromAdvice 输出编码为 JSON（使用 json_encode）并返回。

日志记录交易

您可以选择如何实现，但您可以直接序列化或使用 json_encode 编码 KeksTransaction 实例。

退款

要退款，通过调用构造函数并传入相应的 KeksSeller 和 KeksTransaction 实例来创建一个 KeksRefund。

$KeksRefund = new \KeksPHP\KeksRefund($KeksSeller, $KeksTransaction);

然后，您可以选择一条路径。

仅生成退款请求，但不发送

如果您想自己发送退款请求，可以使用 KeksPHP 创建退款，但不发送 - 使用 createRefund 方法，将其唯一参数设置为 要退款的金额。然后，您可以通过 KeksRefund 实例的 RefundRequest 成员访问它。

$KeksRefund->createRefund($Amount);

your_function_to_send_refund_request($KeksRefund->RefundRequest)

这将不会验证 KEKS 支付响应，因此如果您需要验证，请调用 validateKeksResponse 方法，并将其 KEKS 支付 API 响应体作为其唯一参数。

$KeksRefund->validateKeksResponse($KeksReponse);

这将更改类的 RefundSuccessful 成员为 true 或 false。（默认为 false）

为我做所有事情

如果您希望 KeksPHP 代您发送退款请求，首先使用 createRefund 方法生成它，将其唯一参数设置为 要退款的金额。

然后调用 submitRefund 方法将退款发送到 KEKS 支付，并检查 RefundSuccessful 成员以查看退款是否成功。

$KeksRefund->createRefund($Amount);

$KeksRefund->submitRefund();

if($KeksRefund->RefundSuccessful){
	echo 'yay, successfull refund!';
}
else{
	echo 'oh no, I could not refund!';
}

可能的问题

如果 要退款的金额 高于 原始交易金额，您将收到一个 KeksIntegrationException。

异常

如果在 KeksPHP 的 KeksTransaction 方法中发生异常，它将尝试处理它并将它存储在自身的 handledExceptions 成员中，您可以使用该类的 getExceptions 方法访问它。

如果在 KeksRefund 中发生异常，您会收到它，因为没有恢复的机会。

KeksPHP 抛出的所有异常都是 KeksIntegrationException 类型，它扩展了 PHP 的通用异常，以便在可能的情况下提供适用的 KeksSeller、KeksTransaction 和 KeksRefund 交易，以简化调试。

您可以通过分别访问异常的 KeksSeller、KeksTransaction 和 KeksRefund 成员来访问这些信息。

支持和虫子

有关此项目的疑问和问题，请在此处打开一个问题。（这里也可以使用克罗地亚语！）

有关 KEKS 支付的疑问，请联系 KEKS 支付团队。

mbmjertan / keksphp

维护者

详情