README

这是HarmonyPay自托管服务的PHP API。该API使用JSON对象进行通信。

要使用该API，您必须实现以下功能：

• 通信（GET POST请求）
• 存储
• 标记支付为完成、退款或取消

已包含一个完整的Wordpress实现。要查看API的实际应用，请参阅HarmonyPay Wordpress插件。

要求

• Composer
• PHP 5.6

安装

composer require harmonypay/api

API组件

API 组件是主要类。它处理与API服务器的通信，并为其他组件提供基本服务，例如数据存储和检索。

Account 组件提供与存储的账户数据相关的功能。货币信息、汇率、支付信息、预留金额等。

Payments 组件处理将支付数据添加到API服务器以及取消支付数据。它接收来自API组件有关取消或完成支付的消息。

其他类

Client_Account_Data 是在检索账户时发送到服务器的数据，包含有关安装的信息。

Payment 包含发送到服务器的订单数据：货币、金额、接收者钱包地址等。它有一个 $data 属性，可以用来存储任意属性。

Payment_Data 是用于Payment类内的智能数据处理器。

与API服务器的通信

本节解释了与服务器通信的理论。基本原理如下：

• 通过发送JSON对象来回通信。
• 客户端有一个秘密密钥。
• API服务器知道客户端的秘密密钥。
• 密钥由客户端和API服务器共同使用以授权自身。
• 客户端必须跟踪其自己的账户数据。
• 客户端可以从服务器请求其账户数据。
• 此 retrieve_account 请求使用 retrieve_key 确保只有服务器向客户端发送账户数据。
• 客户端向服务器发送支付信息。
• 服务器向客户端发送支付取消/完成更新。
• 秘密密钥确保只有服务器可以向客户端发送支付更新。

用法

为了使本文档灵活，当提到基本命名空间 harmonypay\api\vx 时，x 是您要实现的API版本号。

基本类大多是抽象的，需要您实现各种方法。

API

首先创建一个扩展 harmonypay\api\vx\API 的类。您需要实现以下方法：

• delete_data - 从持久存储中删除数据。
• get_data - 从持久存储中检索数据。
• get_client_url - 返回此服务器使用的URL。
• is_retrieve_key_valid - 返回指定的检索密钥是否与存储中存储的密钥匹配。
• save_data - 将数据存储到持久存储中。
• send_get - 向URL发送GET请求。
• send_post - 向URL发送POST请求，带有数据数组。

创建您的API类后，您可以实例化它。

创建API实例：$api = new \mytest\api\API();

API可以创建其他组件。

$account = $api->account(); $payments = $api->payments();

由于消息是从服务器发送的，客户端必须能够处理它们，如果它们到达的话。

$api->maybe_process_messages();

上述方法将检查$_POST变量中是否有关HarmonyPay的消息，并将处理它们。如果$_POST中没有来自服务器的任何内容，它将直接返回。

账户

账户组件负责从服务器检索账户数据。要获取或更新账户数据

$account->retrieve();

这将导致以下事件

• 本地生成检索键。
• 将键放入Client_Account_Data。
• 将数据发送到服务器。
• 服务器通过在另一个线程中联系客户端来回复新的账户数据。
• 由于这是在另一个线程中完成的，因此检索键必须放在两个线程都可以访问的地方。
• 新线程检查新数据并查看检索键是否与存储的匹配。
• 如果是这样，则存储新数据。
• 原始线程从服务器接收到OK。全部完成。

服务器在单独的调用中发送数据的原因是为了确保

• 客户端URL是正确的
• 发送者没有伪造

数据检索后，您可以访问各个部分。

$account->get_currency_data(); 或 $account->has_payments_left();

有关更多方法，请参阅Account.php文件。

支付

支付组件负责将支付数据发送到服务器并处理支付更新。

HarmonyPay的支付是区块链上的预期交易。它有一个唯一的ID，当创建支付或支付状态改变时，服务器将向客户端发送这个唯一的ID。这是您需要存储的内容。

您还应存储其他支付信息，例如预期金额、货币、钱包地址等。

您的类将扩展 Payments 类并需要实现以下功能

• cancel_local - 服务器告诉客户端标记支付为已取消。
• complete_local - 服务器告诉客户端标记支付为已完成。

首先创建一个Payment对象。

$payment = $api->payments()->create_new();

然后填充数据

$payment->set_currency_id( 'ONE' ); $payment->set_amount( 50 ); $payment->set_to( 'my_wallet_address' );

然后将它发送到API。

在设置金额之前，请检查金额是否已被其他交易预留。账户数据存储了每个货币的预留金额数组。如果您想要的金额已被预留，请增加一个小数点，直到找到一个未预留的金额。

$payment_id = $api->payments()->add( $payment );

将$payment_id存储在与所售商品相关的地方。在Wordpress WooCommerce中，这将是在订单元数据中。

您需要在服务器上取消支付吗？

$api->payments()->cancel( $payment_id );

服务器可以取消支付，因为支付变得过旧。服务器将发送一个包含支付ID的cancel_payment消息。您的cancel_local方法实现将接收一个具有设置payment_id属性的支付对象。

对于检测到的支付也适用：客户端将接收到一个包含支付ID和交易ID的complete_payment消息。您的complete_local方法实现将接收一个具有设置payment_id和transaction_id属性的支付对象。

文档结束

如果您有任何疑问，请通过harmonypay.com联系我们。