从第一笔订单，到可靠的 Webhook。

创建最小权限 API 密钥

在商户后台选择项目，并为 API 密钥设置权限范围与有效期。密钥只显示一次，轮换后旧密钥立即失效。

安装 TypeScript SDK

pnpm add @payme/sdk@0.1.0-beta.1

锁定明确版本并纳入依赖更新流程，确保生产集成可重复构建。

幂等创建支付订单

import { PayMeClient } from "@payme/sdk";

const payme = new PayMeClient({ apiKey: process.env.PAYME_API_KEY! });

const order = await payme.createPaymentIntent({
  projectId: "proj_test_…",
  externalOrderId: "order_1042",
  amount: "49.00",
  pricingCurrency: "USDT",
  payAsset: "USDT",
  payNetwork: "TRON",
  title: "Design retainer"
}, { idempotencyKey: "order_1042" });

console.log(order.checkout_url);

使用原始请求体验证签名

import { verifyWebhookSignature } from "@payme/sdk";

const valid = verifyWebhookSignature(
  process.env.PAYME_WEBHOOK_SECRET!,
  Number(request.headers.get("payme-timestamp")),
  await request.text(),
  request.headers.get("payme-signature") ?? ""
);

签名消息为 timestamp + "." + raw body，头格式为 v1=…，默认容忍 5 分钟时钟偏差。

记录请求 ID

所有错误均返回稳定的错误码、说明和请求 ID。遇到 429 或 5xx 响应时，可使用同一幂等键进行退避重试；参数或权限错误应先修正请求。

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_payment_amount",
    "message": "…",
    "request_id": "req_…"
  }
}