PISCES

主题

官方 SDK ​

平台提供四种语言的官方 SDK，已封装签名计算、nonce 防重放、回调验签、错误处理与商户单号幂等重试，推荐优先使用，避免手写签名引入对接问题（中文转义、数组键序、/ 转义等均为常见踩坑点）。

一致性保证

四种 SDK 通过同一组后端实测签名向量驱动测试（CI 门禁），签名行为与平台逐字节一致。

安装 ​

PHP（Packagist） ​

bash
composer require crow220/huanyu-sdk-php

Go ​

bash
go get github.com/crow220/huanyu-sdk-go

Python（PyPI） ​

bash
pip install huanyu-sdk

Java（Maven） ​

xml
<dependency>
    <groupId>io.github.crow220</groupId>
    <artifactId>huanyu-sdk-java</artifactId>
    <version>1.0.0</version>
</dependency>

快速上手（以 PHP 为例） ​

php
use HuanyuSdk\Client;
use HuanyuSdk\Exception\HuanyuApiException;

$client = new Client('你的api_key', '你的api_secret');

// 创建订单（金额参数为 cny_amount，字符串形式）
try {
    $order = $client->createOrder([
        'order_type'        => '1',            // 1=买入 2=卖出
        'cny_amount'        => '100.00',
        'merchant_order_no' => 'M20260901001', // 商户内唯一，重复会被拒绝
    ]);
} catch (HuanyuApiException $e) {
    if (strpos($e->getMessage(), '商户单号已存在') !== false) {
        // 超时重试时凭同一单号查单确认，不要重复下单
        $order = $client->orderDetail(['merchant_order_no' => 'M20260901001']);
    } else {
        throw $e;
    }
}
// 买单三要素未通过时 result_status 为 pending_identity，
// 引导用户访问 $order['identity_url'] 补全

// 查询订单（id / order_no / merchant_order_no 三选一）
$detail = $client->orderDetail(['order_no' => $order['order_no']]);

回调验签：

php
use HuanyuSdk\CallbackVerifier;

$verifier = new CallbackVerifier('你的api_secret');
if (!$verifier->verify($_POST)) {
    http_response_code(403);
    exit;
}
// ...业务处理
echo 'success'; // 必须响应 HTTP 200 且含 success，否则平台共推送 5 次（首次 + 4 次重试）

其余语言（Go / Java / Python）用法同构，完整示例见各仓库 README。

源码与反馈 ​

语言仓库
PHPhttps://github.com/Crow220/huanyu-sdk-php
Javahttps://github.com/Crow220/huanyu-sdk-java
Gohttps://github.com/Crow220/huanyu-sdk-go
Pythonhttps://github.com/Crow220/huanyu-sdk-python
共享规格与测试向量https://github.com/Crow220/huanyu-sdk-common

使用建议

  • SDK 每次请求自动生成全新的 timestamp / nonce / signature（nonce 时间窗内一次性有效），失败后直接再次调用即可，不要缓存复用请求参数。
  • 卖单的 payment_method（收款方式）为对象参数，其字段顺序参与签名，请按业务字段顺序构造。