GLOBEPAY 开放平台 v1.0.0 API

GlobePay 开发者技术参考文档

纯原生高并发、严格整数分精度、企业级高可用聚合支付网关开放平台。支持 HMAC-SHA256 安全签名与防重放、收银台动态渲染与 Webhook 毫秒级异步通知。

快速接入概述

在接入 GlobePay OpenAPI 前,请确保已在商户控制台完成如下准备工作:

  1. 开通商户并审核通过:在首页「申请入驻」后,经管理员复核通过即可激活商户身份。
  2. 自主签发 API Key:登录商户后台前往「API 密钥」,一键签发全新的 App Key ID (如 GP_...) 与 64 位通信 Secret。
  3. 配置通知域名:确保业务服务器已对外开放 HTTPS Webhook 接收地址。

核心设计原则与规范

⚠️ 严格金额分精度法则: 系统所有涉及金额的字段(如 amount、payable_amount)一律使用整数分(Cents)表示。1.00 元请传入 100,严禁使用带小数点的浮点数字符串或 float 类型!
  • 请求编码与传输:所有接口统一采用 UTF-8 编码与 application/json 格式传输,必须在 HTTPS 加密信道下通信。
  • 全局时间标准:系统内部全量时间采用严格 UTC 时区与微秒精度(YYYY-MM-DD HH:mm:ss.uuuuuu 或 ISO-8601)。
  • 商户级业务幂等:通过商户自生成唯一单号(merchant_order_no 与 merchant_refund_no)实现天然防重入与幂等保护。

安全鉴权与 HMAC-SHA256 签名机制

GlobePay 对每一个进站 API 请求进行严格的防重放、防篡改与签名验证。商户必须在 HTTP 请求头中携带以下 4 个标准报头:

Header 键名必填说明与格式规范
X-Key-Id必填商户在控制台生成的 API Key ID(如 GP_...)
X-Timestamp必填发起请求的当前 Unix 秒级时间戳(10位纯数字),服务器校验防倾斜窗口为 ±300 秒
X-Nonce必填客户端生成的 16~96 位高强度唯一随机串,用于底层 Redis/MySQL 防重放攻击
X-Signature必填基于 HMAC-SHA256 算法计算出的 64 位十六进制签名小写字符串

规范化待签名字符串 (Canonical Request) 构建规则

签名源串按换行符 \n 严格拼接 5 个元素(末尾不追加换行):

CANONICAL STRING SPECIFICATION
HTTP_METHOD + "\n" +
API_PATH + "\n" +
TIMESTAMP + "\n" +
NONCE + "\n" +
SHA256_HEX(RAW_REQUEST_BODY)
提示:若请求方法为 GET,请求 Body 为空字符串,则最后一行 SHA256_HEX("") 的值为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。

在线 HMAC 签名调试器 (Signature Playground)

您可以在下方实时输入接口入参,调试器将自动在浏览器本地生成待签名原始串、SHA-256 哈希及对应的 cURL 请求命令:

1. 待签名源串 (Canonical String)

              
2. HMAC-SHA256 签名值 (X-Signature)
3. 生成的 cURL 调试命令

              

官方客户端 SDK (Official SDKs)

为进一步降低接入复杂度、防止签名计算偏差,平台为商户提供纯原生、零第三方依赖(Zero External Dependencies)的官方语言 SDK,开箱即用,无需任何 Composer / pip / npm 外部包管理器强制构建:

🐘 PHP 8.0+ 原生 SDK 原生 curl / hash

纯单文件封装,原生兼容严格类型、毫秒级调用、支持 Webhook 验签。

文件路径: sdk/php/GlobePay.php
🐍 Python 3.8+ 原生 SDK 原生 urllib / hmac

无需 requests / cryptography 依赖,标准库开箱即用,内置异常捕获。

文件路径: sdk/python/globepay.py
⚡ Node.js 14+ 原生 SDK 原生 https / crypto

Promise 异步设计,无需 axios / node-fetch,单文件即插即用。

文件路径: sdk/nodejs/globepay.js

SDK 统一方法速查表

方法名称对应 HTTP 接口参数说明与用途
createPayment(array $params)POST /api/v1/payments统一下单并获取聚合收银台或渠道跳转凭证
queryPayment(string $orderNo)GET /api/v1/payments/{orderNo}按商户订单号或平台单号查询支付状态
closePayment(string $orderNo, string $reason)POST /api/v1/payments/{orderNo}/close关闭未支付的订单
createRefund(array $params)POST /api/v1/refunds提交原路退款申请(支持部分退款与全额退款)
queryRefund(string $refundNo)GET /api/v1/refunds/{refundNo}查询退款进度与渠道履约状态
verifyWebhook(string $body, string $id, string $time, string $sig, string $pubKey)本地 RSA-SHA256 验签商户服务端回调安全验签,返回 boolean

快速调用示例 (以 PHP 为例)

PHP 8.0+ SDK QUICKSTART
<?php
declare(strict_types=1);

require_once __DIR__ . '/sdk/php/GlobePay.php';

use GlobePay\GlobePayClient;
use GlobePay\GlobePayException;

$client = new GlobePayClient(
    keyId:      'GP_YOUR_APP_KEY_ID',
    secret:     'sec_your_communication_secret_string',
    gatewayUrl: 'https://gateway.example.com'
);

try {
    // 1. 发起下单
    $order = $client->createPayment([
        'merchant_order_no' => 'ORDER_' . date('YmdHis') . '_' . bin2hex(random_bytes(4)),
        'amount'            => 100, // 严格整数分 (1.00 元)
        'currency'          => 'CNY',
        'subject'           => 'VIP 会员月度订阅',
        'notify_url'        => 'https://merchant.example.com/webhook',
        'return_url'        => 'https://merchant.example.com/return',
    ]);
    
    // 获取收银台地址直接引导客户支付
    $cashierUrl = $order['checkout']['cashier_url'];
    echo "支付跳转地址: " . $cashierUrl;

} catch (GlobePayException $e) {
    echo "下单失败: [" . $e->getErrorCode() . "] " . $e->getMessage();
}

统一下单接口 (Create Payment)

POST /api/v1/payments

创建一笔待支付订单。成功响应将同步返回 checkout 收银台凭证,商户可直接引导用户跳转或扫码。

请求参数 (Request Body JSON)

字段名类型必填描述
merchant_order_nostring必填商户系统唯一订单号(≤ 48位,支持字母、数字与下划线)
amountint必填实付金额,严格整数分精度(如 100 代表 1.00 元)
currencystring选填币种代号,默认 CNY
subjectstring必填商品或交易简短描述(≤ 128字符)
notify_urlstring必填支付完成后异步通知 Webhook 回调地址
return_urlstring选填用户完成支付后前端页面自动跳转地址
method_codestring选填指定支付通道(alipay、wechat 或留空展示聚合收银台)

多语言接入示例代码

curl -X POST "https://gateway.example.com/api/v1/payments" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: GP_TEST_KEY_01" \
  -H "X-Timestamp: 1760000000" \
  -H "X-Nonce: a1b2c3d4e5f6g7h8" \
  -H "X-Signature: 6f9b2d8...c4" \
  -d '{
    "merchant_order_no": "ORD_20261009_001",
    "amount": 100,
    "currency": "CNY",
    "subject": "高级会员订阅",
    "notify_url": "https://merchant.example.com/webhook",
    "return_url": "https://merchant.example.com/pay/return"
  }'

成功响应 (HTTP 200 / 202)

{
  "code": "SUCCESS",
  "message": "OK",
  "data": {
    "order_no": "202610091234567890",
    "merchant_order_no": "ORD_20261009_001",
    "amount": "100",
    "currency": "CNY",
    "status": "pending",
    "refunded_amount": "0",
    "refund_reserved_amount": "0",
    "expires_at": "2026-10-09 13:00:00.000000",
    "paid_at": null,
    "checkout": {
      "token": "chk_9a8b7c6d5e4f3a2b1c",
      "cashier_url": "https://gateway.example.com/cashier/chk_9a8b7c6d5e4f3a2b1c",
      "expires_at": "2026-10-09 13:00:00.000000"
    }
  }
}

查询支付订单 (Query Payment)

GET /api/v1/payments/{order_no}

通过 GlobePay 平台订单号查询订单实时生命周期与支付状态。

RESPONSE EXAMPLE (PAID)
{
  "code": "SUCCESS",
  "data": {
    "order_no": "202610091234567890",
    "merchant_order_no": "ORD_20261009_001",
    "amount": "100",
    "currency": "CNY",
    "status": "paid",
    "refunded_amount": "0",
    "paid_at": "2026-10-09 12:45:10.123456"
  }
}

关闭支付订单 (Close Payment)

POST /api/v1/payments/{order_no}/close

关闭未支付或已超时的支付订单,防止买家重复支付。请求 Body 传空 JSON 对象 {}。

申请退款接口 (Create Refund)

POST /api/v1/refunds

对已成功支付的订单发起整单或部分退款申请。

字段名类型必填说明
order_nostring必填原平台支付订单号
merchant_refund_nostring必填商户唯一退款单号(≤ 48字符)
amountint必填退款金额(整数分,不得超过剩余可退金额)
reasonstring必填退款依据原因说明

查询退款订单 (Query Refund)

GET /api/v1/refunds/{refund_no}

通过平台退款单号查询该笔退款执行状态(requested、processing、succeeded 或 failed)。

Webhook 异步通知与验签规范

支付或退款成功后,GlobePay 将向商户统一下单时指定的 notify_url 发起 HTTP POST 通知。为了确保通知来源的真实性与报文完整性,系统使用平台私钥生成 RSA-SHA256 签名,并在报头中传递。

通知 HTTP Headers

Header 键名描述
X-Notification-Id通知任务唯一单号(如 NOT202610...)
X-Notification-Version固定为 1
X-Key-Id签发密钥唯一代号
X-Timestamp发送秒级时间戳
X-SignatureBase64 编码的 RSA-SHA256 签名值

商户端 RSA-SHA256 验签算法

商户端使用平台公钥验证签名有效性:

PHP 8.1+ WEBHOOK VERIFICATION
<?php
declare(strict_types=1);

$rawBody        = file_get_contents('php://input');
$notificationId = $_SERVER['HTTP_X_NOTIFICATION_ID'] ?? '';
$timestamp      = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$signatureB64   = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// 构建待验签源串:NotificationId\nTimestamp\nSHA256(RawBody)
$message = $notificationId . "\n" . $timestamp . "\n" . hash('sha256', $rawBody);

$platformPublicKey = file_get_contents('/path/to/globepay_platform_public.pem');
$ok = openssl_verify($message, base64_decode($signatureB64), $platformPublicKey, OPENSSL_ALGO_SHA256);

if ($ok !== 1) {
    http_response_code(401);
    exit('SIGNATURE_VERIFY_FAILED');
}

// 验签通过,解析业务报文
$event = json_decode($rawBody, true);
// ... 处理订单履约逻辑 ...

// 商户应答规范:返回 HTTP 200 及 SUCCESS JSON
header('Content-Type: application/json');
echo json_encode(['code' => 'SUCCESS', 'message' => 'OK']);
商户应答规范:商户系统处理完成后必须在 5 秒内返回 HTTP 200 状态码及 {"code":"SUCCESS","message":"OK"}。若响应超时或返回非 200,网关将按照指数退避策略自动重试投递(最大重试 8 次)。

状态码与错误代码字典

HTTP 状态码错误代码说明与排查指引
200 OKSUCCESS操作执行成功
400 Bad RequestINVALID_REQUEST参数校验错误、缺少必填字段或格式不符合规范
401 UnauthorizedAUTH_FAILEDAPI 鉴权失败:签名不匹配、密钥不存在、时间戳偏差超过 300 秒或 Nonce 重复
403 ForbiddenFORBIDDEN商户未开通对应接口权限,或商户状态非 active
403 ForbiddenRISK_DENY被事中风控引擎拦截(如命中黑名单、超额限额限制)
404 Not FoundNOT_FOUND指定的订单号或资源不存在
409 ConflictINVALID_STATE业务状态机冲突(例如试图关闭已支付的订单)
413 Payload Too LargePAYLOAD_TOO_LARGE请求体超过 64KB 限制
429 Too Many RequestsRATE_LIMIT_EXCEEDED触发每秒请求频控限流保护