README

我们的即时支付供应商API允许用户作为供应商并接收付款的即时通知。

这允许您通过在线电子商务、零售ePOS（电子销售点）或我们的移动应用接受ETN作为即时付款，并确保付款正在途中。

将在您的账户上创建一个即时通知，您可以通过移动应用访问，以确认付款正在途中。

使用HTTP RESTful功能，我们的API在付款给您时可以可选地发送一个签名webhook。您通过确认webhook的签名来验证此操作。

您可以在 my.electroneum.com/register 上注册Electroneum用户账户，并在 my.electroneum.com/user/vendor 上申请供应商账户。

当您的集成上线时，请告诉我们，我们很高兴分享这个消息！您可以在 Twitter、Facebook 或在社区论坛上分享图片和视频。

状态

此API目前处于BETA阶段。在此阶段，我们不承担任何错误通知的责任，也不确认任何供应商的身份。

每笔交易的最大支出限额为500.00欧元；此数额根据市场价格定期转换为ETN。请不要尝试向用户展示超过此限额的二维码，因为交易将失败。

在此阶段应使用 composer 的 beta 版本。

变更日志

所有发布的更改都将在此部分中记录。

2020-09-01

支持 bcmath 精度

2019-07-31

添加了货币 KHR

2019-03-22

添加了更多货币：ARS、BDT、COP、EGP、GHS、NGN、RON、UAH、VES、VND
删除了 VERSION.md 并将 CHANGELOG.md 移动到 README.md
用 QR Server 替换了 Google Chart 以生成 QR 图像

2018-10-01

修复了 /example/poll-confirmation.php 中的有效负载顺序
更新了 URL_SUPPLY 以使用 cUrl（首选于 file_get_contents()）并在两者都不可用的情况下抛出异常 - 由 Benjaminoo 报告并推荐修复
远程API更新包括
- 轮询确认签名现在不区分大小写
- Webhook响应现在包括一个 event 参数
- 轮询HTTP响应已更新为 200，从 400 的 status: 0

2018-09-10

Electroneum供应商PHP API的第一个beta版本发布

支持

社区支持可在 community.electroneum.com 获取。

文档

有关数据结构（用于创建自己的集成或自己创建QR码）和我们的供应商API的更多文档可在 community.electroneum.com 找到。

要求

使用供应商API需要以下内容

启用了供应商API的Electroneum用户账户
PHP v5.4.0或更高版本，并具有以下扩展
- ext-bcmath（可选，推荐）
- ext-ctype
- ext-curl（或启用 allow_url_fopen）
- ext-json

下载

您可以从 github.com/electroneum/vendor-php 下载最新的 PHP API。

安装

手动安装

解压缩 API 并包含 Electroneum 供应商类

require_once 'src/vendor.php';

Composer 安装

使用 composer，您可以轻松地安装

composer require electroneum/vendor-php dev-beta

或者，您可以将以下内容添加到您的 composer.json

"require": {
    "electroneum/vendor-php": "dev-beta"
},
"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/electroneum/vendor-php"
    }
],

快速使用

这是使用我们的供应商 API 的 PHP 快速指南。

为顾客生成 QR 码

// Create the Vendor object.
$vendor = new \Electroneum\Vendor\vendor(
    'key_live_1234567890abcdefghijklm',
    'sec_live_zxyxwvutsrqponmlkjihgfedcba0987654321zxyxwvutsrqponmlkj'
);

// Create a QR code, passing the amount to charge, currency & outlet id.
$qrImgUrl = $vendor->getQr(9.95, 'GBP', '0abc123def456');
$paymentId = $vendor->getPaymentId();

监听确认支付的 webhook

// Get the payload and signature from an incoming webhook.
$payload = @file_get_contents('php://input');
$signature = @$_SERVER['HTTP_ETN_SIGNATURE'];

// Verify the signature.
if ($vendor->verifySignature($payload, $signature)) {
    http_response_code(200);

    // Process the transaction.
    $payload = json_decode($payload);
    ...
} else {
    http_response_code(401);
}

入门

只需创建一个 Vendor() 对象。除非您正在验证 webhook 签名或轮询支付确认（见下文），否则您不需要传递任何变量

$vendor = new \Electroneum\Vendor\vendor();

创建 QR 码

为了接受供应商即时支付通知，您需要向顾客展示一个包含必要信息的 QR 码，以便他们使用手机上的 Electroneum 应用扫描。

您可以使用 Vendor 对象的 getQr($amount, $currency, $outlet, $paymentId = null) 方法来创建此 QR 码，以下是需要传入的参数

$amount
以您的本地货币为单位的收费金额（可接受货币见下文）。
$currency
您的本地货币代码（见下文列表）。
$outlet
您用户供应商账户的 id，可从您的用户供应商账户获取。
$paymentId
此交易的唯一标识符。如果没有提供，这将自动生成。

getQr() 方法将返回 QR 码图像的 Google Chart URL。

$currency 必须是以下三位代码之一

paymentId 将存储在供应商对象中。如果您自动生成了此值，您可以使用 getPaymentId() 方法检索此值。

例如

$qrImgUrl = $vendor->getQr(9.95, 'GBP', '0abc123def456');
$paymentId = $vendor->getPaymentId();

支付小部件

如果您是线上供应商，您可能希望使用我们的供应商支付小部件，该小部件将 getQr() 返回的字符串显示为可扫描的 QR 码或可点击的链接。这对于有人使用手机设备访问您的在线商店非常有用。有关详细信息，请参阅我们的 API 指南。

Webhook

如果您在您的用户供应商账户中提供了 webhook URL，则带签名的 webhook 将发送到此 URL。

发送 webhook 的用户代理将指示 API 版本、API 集成指南的 URL，并且始终以 Electroneum/ 开头。例如 Electroneum/1.0 (+https://electroneum.com/instant-payments)。

有效负载将作为请求体发送，并包括事件类型和事件详情。该 event 将是 payment 或 refund。

签名作为 webhook 中的 ETN-SIGNATURE HTTP 头部发送，并使用您的 API 秘密计算有效负载的 SHA256 哈希值。

要验证有效负载的签名，您需要使用您的 API 密钥 & 秘密创建 Vendor 对象

$vendor = new \Electroneum\Vendor\vendor(
    'key_live_1234567890abcdefghijklm',
    'sec_live_zxyxwvutsrqponmlkjihgfedcba0987654321zxyxwvutsrqponmlkj'
);

然后，您可以通过调用 verifySignature() 来验证有效负载，这将返回一个布尔响应

$payload = @file_get_contents('php://input');
$signature = @$_SERVER['HTTP_ETN_SIGNATURE'];
$verify = $vendor->verifySignature($payload, $signature);

为了防止重放攻击，verifySignature() 方法将验证时间戳是最近的，在过去 5 分钟内，以允许不准确的时钟同步，并让顾客完成支付过程。

我们建议您通过使事件处理无状态来检查重复的 webhook；将付款记录为已处理，以便如果您收到重复的 webhook 支付 ID，您可以立即忽略它。

如果您收到有效的webhook签名，您就可以放心地继续进行交易，因为您知道负载中指定的金额已发送。

响应

在接收webhook时，您必须返回有效的HTTP响应代码。为了避免我们的webhook超时，您应尽快返回HTTP响应。

成功必须返回2XX代码，例如200。这将让我们知道您已成功接收webhook且它有效。

任何错误应返回4XX代码，例如401。

失败的webhook/重试

对于我们的webhook的任何响应，如果不是成功的代码（不是2XX），将会提醒我们应重试webhook。webhook每小时重试一次，连续三天后不再重试。

为了避免接收多个webhook，确保您的监听器是无状态的，并尽快返回成功的HTTP响应。

生成测试webhook

一旦您设置了您的供应商账户，您就可以从您的用户供应商账户生成测试webhook。

这将生成一个随机的webhook负载和有效的签名，您可以使用REST客户端（如Insomnia REST客户端）来测试接收器。我们不会将负载和签名推送到您的webhook URL进行此测试。

轮询支付确认

如果您无法打开您的网络或ePOS以接收webhook通知，那么您可以轮询我们的服务器以确认是否已发送支付。

您需要发送您的支付ID和供应商地址的JSON。将使用您供应商对象中已存在的秘密密钥创建负载的签名。

$result = $vendor->checkPaymentPoll(json_encode([
    'payment_id' => '7ce25b4dc0',
    'vendor_address' => 'etn-it-0abc123def456'
]));

生成的JSON将包括

状态
0 支付未发送
1 支付已发送
消息
如果状态是0，将返回错误消息。
金额
如果状态是1，将返回客户支付的ETN金额。

为了避免被我们的API阻止，请将您的轮询限制为每秒不超过一次请求。

electroneum / vendor-php

维护者

详细信息