jinso / pay-sdk

v1.0.0 2026-09-04 08:42 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

Published on Packagist.org on 2026-09-04 08:44 UTC

README

业务系统接入 Jinso 统一支付开放 API 的 PHP 客户端。无 Guzzle 依赖，只需 PHP 8.1+、curl、json。

安装

源码：https://github.com/yangxiaozhan/jinso-pay-sdk

Packagist 收录后：

composer require jinso/pay-sdk:^1.0

收录前可先用 GitHub：

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/yangxiaozhan/jinso-pay-sdk.git"
    }
  ],
  "require": {
    "jinso/pay-sdk": "^1.0"
  }
}

凭证

在 Jinso 管理后台 应用管理 → 新建应用，一次性拿到：

字段	用途
app_id	请求头 X-App-Id
key_id	请求头 X-Key-Id
secret	开放 API HMAC 签名
notify_secret	回调验签（与 secret 不是同一把）

用法

use Jinso\Pay\JinsoClient;
use Jinso\Pay\JinsoException;

$client = JinsoClient::staging($appId, $keyId, $secret);
// 生产：$client = JinsoClient::production($appId, $keyId, $secret);

try {
    // 付款码被扫（当前真实渠道可用）。金额单位：分
    $order = $client->barcodePay(
        outTradeNo: 'T'.date('YmdHis'),
        amountFen: JinsoClient::yuanToFen(0.01),
        subject: '门店收款',
        authCode: $authCode,
        extra: ['notify_url' => 'https://biz.example.com/jinso/notify'],
    );
    // $order['status'] => created | paying | success | failed
    // $order['order_no'] 平台单号

    $order = $client->queryPayment($order['out_trade_no']);
    $refund = $client->refund($order['out_trade_no'], 'R'.date('YmdHis'), 1, '测试退款');
} catch (JinsoException $e) {
    // $e->getMessage()  $e->httpStatus  $e->errorCode
}

H5 / 正扫（协议可用；微信支付宝真实下单尚未接通时请用 channel: mock 联调签名）：

$client->createPayment([
    'out_trade_no' => 'T1001',
    'pay_scene' => 'qrcode', // 或 h5
    'channel' => 'mock',
    'amount' => 1,
    'subject' => '联调',
]);

回调验签

平台向 notify_url POST JSON。业务须返回 HTTP 2xx。

$payload = json_decode(file_get_contents('php://input'), true);
if (! JinsoClient::verifyNotify($payload, $notifySecret)) {
    http_response_code(401);
    exit;
}
// payment.success / payment.closed / refund.success
http_response_code(200);
echo 'ok';

完整示例见 examples/barcode_pay.php、examples/notify.php。

环境

方法	API
JinsoClient::staging(...)	https://staging-api.jinso.cdfcz.com
JinsoClient::production(...)	https://api.jinso.cdfcz.com
new JinsoClient($baseUrl, ...)	自定义（如本地 http://127.0.0.1:8000）

签名说明

请求签名原文（\\n 拼接）：METHOD + /api/v1/... + timestamp + nonce + raw JSON body（GET 的 body 为空字符串）。