GlobePay 开发者技术参考文档
纯原生高并发、严格整数分精度、企业级高可用聚合支付网关开放平台。支持 HMAC-SHA256 安全签名与防重放、收银台动态渲染与 Webhook 毫秒级异步通知。
快速接入概述
在接入 GlobePay OpenAPI 前,请确保已在商户控制台完成如下准备工作:
- 开通商户并审核通过:在首页「申请入驻」后,经管理员复核通过即可激活商户身份。
- 自主签发 API Key:登录商户后台前往「API 密钥」,一键签发全新的
App Key ID(如GP_...) 与 64 位通信Secret。 - 配置通知域名:确保业务服务器已对外开放 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 个元素(末尾不追加换行):
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 请求命令:
官方客户端 SDK (Official SDKs)
为进一步降低接入复杂度、防止签名计算偏差,平台为商户提供纯原生、零第三方依赖(Zero External Dependencies)的官方语言 SDK,开箱即用,无需任何 Composer / pip / npm 外部包管理器强制构建:
纯单文件封装,原生兼容严格类型、毫秒级调用、支持 Webhook 验签。
无需 requests / cryptography 依赖,标准库开箱即用,内置异常捕获。
Promise 异步设计,无需 axios / node-fetch,单文件即插即用。
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
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)
创建一笔待支付订单。成功响应将同步返回 checkout 收银台凭证,商户可直接引导用户跳转或扫码。
请求参数 (Request Body JSON)
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| merchant_order_no | string | 必填 | 商户系统唯一订单号(≤ 48位,支持字母、数字与下划线) |
| amount | int | 必填 | 实付金额,严格整数分精度(如 100 代表 1.00 元) |
| currency | string | 选填 | 币种代号,默认 CNY |
| subject | string | 必填 | 商品或交易简短描述(≤ 128字符) |
| notify_url | string | 必填 | 支付完成后异步通知 Webhook 回调地址 |
| return_url | string | 选填 | 用户完成支付后前端页面自动跳转地址 |
| method_code | string | 选填 | 指定支付通道(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)
通过 GlobePay 平台订单号查询订单实时生命周期与支付状态。
{
"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)
关闭未支付或已超时的支付订单,防止买家重复支付。请求 Body 传空 JSON 对象 {}。
申请退款接口 (Create Refund)
对已成功支付的订单发起整单或部分退款申请。
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_no | string | 必填 | 原平台支付订单号 |
| merchant_refund_no | string | 必填 | 商户唯一退款单号(≤ 48字符) |
| amount | int | 必填 | 退款金额(整数分,不得超过剩余可退金额) |
| reason | string | 必填 | 退款依据原因说明 |
查询退款订单 (Query Refund)
通过平台退款单号查询该笔退款执行状态(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-Signature | Base64 编码的 RSA-SHA256 签名值 |
商户端 RSA-SHA256 验签算法
商户端使用平台公钥验证签名有效性:
<?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']);
{"code":"SUCCESS","message":"OK"}。若响应超时或返回非 200,网关将按照指数退避策略自动重试投递(最大重试 8 次)。
状态码与错误代码字典
| HTTP 状态码 | 错误代码 | 说明与排查指引 |
|---|---|---|
| 200 OK | SUCCESS | 操作执行成功 |
| 400 Bad Request | INVALID_REQUEST | 参数校验错误、缺少必填字段或格式不符合规范 |
| 401 Unauthorized | AUTH_FAILED | API 鉴权失败:签名不匹配、密钥不存在、时间戳偏差超过 300 秒或 Nonce 重复 |
| 403 Forbidden | FORBIDDEN | 商户未开通对应接口权限,或商户状态非 active |
| 403 Forbidden | RISK_DENY | 被事中风控引擎拦截(如命中黑名单、超额限额限制) |
| 404 Not Found | NOT_FOUND | 指定的订单号或资源不存在 |
| 409 Conflict | INVALID_STATE | 业务状态机冲突(例如试图关闭已支付的订单) |
| 413 Payload Too Large | PAYLOAD_TOO_LARGE | 请求体超过 64KB 限制 |
| 429 Too Many Requests | RATE_LIMIT_EXCEEDED | 触发每秒请求频控限流保护 |