如何获取 Global Payments GP API access token？

2026-10-24支付小周

结论

获取 GP API access token 时，不能直接将 app_key 作为 secret 提交。请求中的 secret 需要按以下公式生成：

secret = SHA512(nonce + app_key)

需要注意：

app_id 和 app_key 必须来自同一套已启用 GP API 的应用凭据。
每次请求都要动态生成唯一的 nonce。
Sandbox 凭据只能发送到 Sandbox 地址，不能与生产环境混用。
请求必须带有正确的 Content-Type 和 X-GP-Version 请求头。

问题中没有提供具体的 HTTP 状态码和错误响应，因此无法确定唯一原因。常见原因包括 secret 计算错误、环境混用、凭据无效或请求头缺失。

正确的请求方式

Sandbox 的 token 地址通常是：

POST https://apis.sandbox.globalpay.com/ucp/accesstoken

生产环境地址通常是：

POST https://apis.globalpay.com/ucp/accesstoken

请求头示例：

Content-Type: application/json
X-GP-Version: 2021-03-22

X-GP-Version 应以当前 GP API 文档或账户配置要求为准。如果文档指定了其他版本日期，请使用文档中的值。

请求体示例：

{
  "app_id": "{{app_id}}",
  "nonce": "{{nonce}}",
  "secret": "{{secret}}",
  "grant_type": "client_credentials"
}

部分账户或接口版本支持 seconds_to_expire，但认证失败通常与这个参数无关。不确定时可以先不传。

在 Postman 中生成 nonce 和 secret

先在 Postman Environment 中创建以下变量：

app_id
app_key
nonce
secret

app_key 不应出现在请求体中。在请求的 Pre-request Script 中加入：

const appKey = pm.environment.get("app_key");

if (!appKey) {
  throw new Error("Postman environment variable app_key is missing");
}

const nonce =
  Date.now().toString() +
  Math.random().toString(36).substring(2);

const secret = CryptoJS
  .SHA512(nonce + appKey)
  .toString(CryptoJS.enc.Hex);

pm.environment.set("nonce", nonce);
pm.environment.set("secret", secret);

请求 Body 选择 raw → JSON：

{
  "app_id": "{{app_id}}",
  "nonce": "{{nonce}}",
  "secret": "{{secret}}",
  "grant_type": "client_credentials"
}

发送前可以通过 Postman Console 检查最终请求，但不要打印或分享 app_key。

使用 Node.js 验证签名

如果怀疑 Postman 计算出的哈希不正确，可以用 Node.js 单独验证：

const crypto = require("node:crypto");

const appKey = process.env.GP_APP_KEY;
const nonce = `${Date.now()}${crypto.randomBytes(16).toString("hex")}`;

if (!appKey) {
  throw new Error("GP_APP_KEY is missing");
}

const secret = crypto
  .createHash("sha512")
  .update(nonce + appKey, "utf8")
  .digest("hex");

console.log({
  nonce,
  secret
});

然后发起请求：

const response = await fetch(
  "https://apis.sandbox.globalpay.com/ucp/accesstoken",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-GP-Version": "2021-03-22"
    },
    body: JSON.stringify({
      app_id: process.env.GP_APP_ID,
      nonce,
      secret,
      grant_type: "client_credentials"
    })
  }
);

const body = await response.text();

console.log(response.status);
console.log(body);

请求成功后，响应会包含后续 API 请求所需的 token。具体字段名称和附加字段以当前 GP API 的响应为准。

常见错误及处理办法

认证失败或凭据无效

依次检查以下内容：

app_id 和 app_key 是否属于同一个应用。
当前使用的是否为 GP API 凭据，而不是后台登录密码、Merchant ID 或其他网关产品的凭据。
Sandbox 凭据是否被发送到了生产地址，或生产凭据是否被发送到了 Sandbox 地址。
复制凭据时是否带入了空格、换行或引号。

secret 无效

必须严格按照以下公式计算：

SHA512(nonce + app_key)

拼接顺序不能写成：

SHA512(app_key + nonce)

同时确认：

使用的是 SHA-512，而不是 SHA-256。
输出结果是十六进制字符串。
除非当前官方文档明确要求，否则不要进行 Base64 编码。
参与哈希计算的 nonce 必须与请求体中的 nonce 完全一致。
nonce 和 app_key 之间不能加入冒号、空格或换行。

nonce 重复或过期

每次发送请求前都应生成新的 nonce，不要长期保存并重复使用同一个值。Pre-request Script 生成新 nonce 后，也必须基于这个新值重新计算 secret，不能继续使用旧 secret。

请求格式错误

Postman 的 Body 应使用原始 JSON，不能使用 form-data 或 x-www-form-urlencoded。请求中还必须包含：

Content-Type: application/json

JSON 属性名也要保持准确。例如，应使用 app_id，不能改成 appId。

API 未真正开通

Sandbox 页面显示 GP API 已启用，不一定表示当前应用凭据已经正确创建、激活并关联到相应账户。如果请求结构和签名都正确，但服务端仍返回应用无效、权限不足或类似错误，需要请 Global Payments 支持人员确认：

app_id 是否已激活；
应用是否关联了正确的 Sandbox 账户；
所需 API 权限是否已经分配；
凭据具体属于哪个 Global Payments 产品或平台。

Global Payments 有多种网关和 API 产品，不同产品的认证方式不能混用。

后续请求的认证

获得 token 后，按照目标接口文档的要求发送认证信息。常见形式是：

Authorization: Bearer <access_token>

同时保留接口要求的版本头：

X-GP-Version: 2021-03-22

不需要为每个业务请求重新生成 token。可以在 token 有效期内复用，并在过期前重新获取。app_key 只能保存在服务端或受保护的环境变量中，不能写入浏览器代码、公开仓库或可共享的 Postman Collection。