PSP 商户 API 对接文档

本文档按 Apifox 常见接口文档方式组织：先说明公共规则，再逐个接口给出接口地址、请求参数、请求示例、返回响应和字段说明。商户按顺序完成即可自主接入。

接入流程

1. 完成接入凭证配置：在 Merchant Portal 的「接入凭证」中创建 Gateway Secret，生成或粘贴商户 Ed25519 公钥。
2. 保存一次性密钥：创建成功后立即保存 API ID、API Key 和商户私钥；API Key 和私钥不能从 PSP 恢复。
3. 配置 Webhook：在「Webhook」页面按商户账户配置 HTTPS 回调地址，并复制该账户的 PSP 验签公钥。
4. 实现公共请求头：请求带上 X-API-ID、X-API-Key、X-Timestamp 和签名；写请求再带幂等键。
5. 实现签名与幂等：写请求必须带 Idempotency-Key，并把幂等键放入签名字符串。
6. 优先联调余额与 PIX 代收：先验证认证链路，再联调异步 Webhook。
7. 接入代付和其他支付方式：代收、代付最终状态以查询接口或 Webhook 为准。

公共信息

环境变量

金额规则

后台配置

以下步骤对应 Merchant Portal 当前页面和弹框。文档中的“商户请求签名公钥”和“PSP Webhook 验签公钥”是两把不同的公钥，请分别按对应章节配置。

1. 创建 Gateway Secret（接入凭证）

1. 登录 Merchant Portal，进入「接入凭证」。在「Gateway Secret 调用凭证」区域点击「创建 Gateway Secret」。
2. 在弹框中选择要调用的「商户账户」、密钥用途（「代收」或「转账」）和环境（staging 或 production）。每个账户、用途和环境应使用对应的凭证。
3. 在「Ed25519 公钥」字段中粘贴已有公钥，或点击「在浏览器中生成密钥对」由浏览器本地生成。生成私钥不会上传到 PSP。
4. 按需填写「描述」「Gateway IP 白名单」、权限范围和过期时间。IP 白名单留空表示拒绝所有外部 Gateway 请求。
5. 提交后保存弹框中的 API ID、API Key、Ed25519 Public Key 和 SHA-256 Fingerprint。API ID、API Key、公钥和权限创建后不能原地修改。
6. 立即点击「下载私钥（仅此一次）」和「下载公钥」。API Key 和私钥只在创建流程中显示或下载一次；私钥只存放在商户服务端密钥系统。

2. 配置账户级 Webhook

1. 进入 Merchant Portal 的「Webhook」页面，使用账户筛选找到目标商户账户。Webhook 配置按账户分别生效。
2. 在账户卡片中点击配置，填写完整的 HTTPS 回调 URL、需要接收的 event type、允许域名、自定义 headers JSON 和描述，然后启用配置并保存。
3. 保存后，在同一账户卡片中点击「复制验签公钥」或「下载当前公钥」，将公钥配置到商户 Webhook 接收服务。
4. 收到通知时，使用该账户的 PSP Webhook 公钥验证 X-Timestamp + "." + raw_body 的 Ed25519 签名。不要使用接入凭证页面上传的商户请求签名公钥。

认证方式

商户 Gateway 使用 Account Secret 认证：X-API-ID 定位账户凭证，X-API-Key 校验密钥，X-Timestamp 防止过期请求，X-Signature 使用 Ed25519 验证请求。Invoice、Transfer、Query Gateway 使用对应类型的 Account Secret。

公共 Header 参数

请求签名

签名算法

读请求签名字符串

读请求也必须签名。签名字符串固定为：

<HTTP_METHOD>
<API_ID>
<MERCHANT_ACCOUNT_ID>
<ESCAPED_PATH>
<CANONICAL_QUERY>
<X-Timestamp>
<IDEMPOTENCY_KEY_OR_EMPTY>
<SHA256_HEX_OF_RAW_BODY>

写请求签名字符串

完整签名串还需以 v1 作为第一行，方法使用大写；query 参数按键和值排序后 URL 编码。无 body 时使用空 body 的 SHA-256。

签名示例

v1
api_test_001
550e8400-e29b-41d4-a716-446655440000
POST
/api/v1/payments/intents

1781440000
ORD-10001
<sha256_hex_of_raw_body>

签名示例代码

Node.js

const crypto = require("crypto");

function signRequest({ method, path, canonicalQuery = "", apiId, merchantAccountId, body = "", idempotencyKey = "", privateKeyPem }) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyHash = crypto.createHash("sha256").update(body, "utf8").digest("hex");
  const payload = ["v1", apiId, merchantAccountId, method.toUpperCase(), path, canonicalQuery, timestamp, idempotencyKey, bodyHash].join("\n");
  const signature = crypto.sign(null, Buffer.from(payload), privateKeyPem).toString("base64");

  return { timestamp, signature, payload };
}

module.exports = { signRequest };

Java

import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import java.security.MessageDigest;
import java.util.HexFormat;

public class PspSigner {
  static PrivateKey loadPrivateKey(String privateKeyPem) throws Exception {
    String pem = privateKeyPem
      .replace("-----BEGIN PRIVATE KEY-----", "")
      .replace("-----END PRIVATE KEY-----", "")
      .replaceAll("\\s", "");
    byte[] keyBytes = Base64.getDecoder().decode(pem);
    return KeyFactory.getInstance("Ed25519").generatePrivate(new PKCS8EncodedKeySpec(keyBytes));
  }

  static String sign(String apiId, String merchantAccountId, String method, String path, String canonicalQuery, long timestamp, String idempotencyKey, String body, PrivateKey key) throws Exception {
    String bodyHash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(body.getBytes(StandardCharsets.UTF_8)));
    String payload = "v1\n" + apiId + "\n" + merchantAccountId + "\n" + method.toUpperCase() + "\n" + path + "\n" + canonicalQuery + "\n" + timestamp + "\n" + idempotencyKey + "\n" + bodyHash;

    Signature signer = Signature.getInstance("Ed25519");
    signer.initSign(key);
    signer.update(payload.getBytes(StandardCharsets.UTF_8));
    return Base64.getEncoder().encodeToString(signer.sign());
  }
}

PHP

<?php
function sign_psp_request($apiId, $merchantAccountId, $method, $path, $canonicalQuery, $timestamp, $idempotencyKey, $body, $privateKeyBase64) {
    $privateKey = base64_decode($privateKeyBase64);
    $bodyHash = hash('sha256', $body);
    $payload = "v1\n" . $apiId . "\n" . $merchantAccountId . "\n" . strtoupper($method) . "\n" . $path . "\n" . $canonicalQuery . "\n" . $timestamp . "\n" . $idempotencyKey . "\n" . $bodyHash;

    $signature = sodium_crypto_sign_detached($payload, $privateKey);
    return base64_encode($signature);
}
?>

接口接入示例

以下接口示例都放在本文档内。创建类接口必须使用 Idempotency-Key，查询类接口不需要 body。

Webhook 通知

PSP 会将代收、代付结果推送到商户配置的 webhook_url。商户需要验证签名、按投递 ID 做幂等处理，并快速返回 HTTP 2xx。API Reference 中的 /api/v1/webhooks/* 是 PSP 接收渠道回调的内部入口，不是商户需要调用的地址。

获取 PSP Webhook 公钥

1. 登录 Merchant Portal，进入「Webhook」，在账户筛选中找到接收通知的商户账户。
2. 先确认该账户已保存 HTTPS endpoint URL。账户卡片会显示配置状态、event type、Key ID、签名算法和 Fingerprint。
3. 点击「复制验签公钥」直接复制当前公钥，或点击「下载当前公钥」保存文件。PSP 只公开验签公钥，不会透露 Webhook 私钥。
4. 在商户 Webhook 接收服务中按账户保存公钥，并使用对应账户的公钥验证通知。不同账户不要混用公钥。

Webhook 公钥轮换

1. 在目标账户卡片点击「准备轮换」，然后点击「下载 next 公钥」。
2. 先把 next 公钥部署到商户接收服务，使服务在过渡期同时支持当前公钥和 next 公钥。
3. 确认服务已部署后，回到后台点击「启用 next 密钥」。确认新旧密钥切换完成后，再从服务端移除旧公钥。

Webhook Header

Webhook Body 示例

{
  "event": "payment.intent.completed",
  "timestamp": "2026-06-14T14:30:00Z",
  "data": {
    "collection_number": "PI_pix_20260614142208_d4a888712b1b",
    "payment_method": "pix",
    "rail_variant": "pix_qr",
    "amount": 10000,
    "paid_amount": 10000,
    "currency": "BRL",
    "merchant_order_id": "ORD-10001",
    "provider_transaction_id": "BRADESCO-IN-xxx",
    "paid_at": "2026-06-14T14:30:00Z"
  }
}

Webhook 事件

Node.js Webhook 验签示例

// npm install tweetnacl
const nacl = require("tweetnacl");

function verifyWebhook(publicKeyBase64, timestamp, rawBodyBuffer, signatureBase64) {
  const publicKey = Buffer.from(publicKeyBase64, "base64");
  const signature = Buffer.from(signatureBase64, "base64");
  const payload = Buffer.concat([Buffer.from(`${timestamp}.`, "utf8"), rawBodyBuffer]);
  return nacl.sign.detached.verify(payload, signature, publicKey);
}

function handleWebhook(req, res) {
  const rawBody = req.rawBody; // 必须是未解析、未格式化的原始 body
  const timestamp = req.headers["x-timestamp"];
  const signature = req.headers["x-signature"];
  const webhookId = req.headers["x-webhook-id"];

  if (!verifyWebhook(process.env.WEBHOOK_PUBLIC_KEY_BASE64, timestamp, rawBody, signature)) {
    res.statusCode = 401;
    res.end("invalid signature");
    return;
  }

  // 用 webhookId 做唯一约束，重复通知直接返回 2xx。
  res.statusCode = 204;
  res.end();
}

联调检查项

幂等重试示例

// 第一次请求
Idempotency-Key: ORD-10001
body_sha256: 6b3f...

// 安全重试：同 key + 同 body
Idempotency-Key: ORD-10001
body_sha256: 6b3f...

// 错误用法：同 key + 不同 body，会返回 422 VALIDATION_ERROR
Idempotency-Key: ORD-10001
body_sha256: 9a01...

错误码