PayRam TypeScript / JavaScript SDK 入门

1. 安装与初始化

官方 SDK 是面向后端的 TypeScript 库，也可以在 JavaScript 项目里使用。

npm install payram
# 或
yarn add payram
pnpm add payram

你需要两样东西：项目 API 密钥和基础地址。基础地址是你打开后台用的地址，在后台 设置 → 站点地址 里查看；PayRamHost 商家的基础地址就是后台所在的地址。官方文档的措辞面向自托管服务器，对接托管服务时原理相同，把基础地址换成你的后台地址即可。

import { Payram } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,     // 必填
  baseUrl: process.env.PAYRAM_BASE_URL!,   // 必填，例如 https://pay.payramhost.com
  config: {
    timeoutMs: 10_000,   // 可选：请求超时
    maxRetries: 2,       // 可选：最大重试次数
    retryPolicy: 'safe', // 可选：重试策略
  },
});

密钥和地址请放在环境变量里，不要写进代码仓库。config 里的各项默认值，以官方文档为准。

2. 创建支付

const checkout = await payram.payments.initiatePayment({
  customerEmail: 'customer@example.com',
  customerId: 'cust_123',
  amountInUSD: 49.99,
});

console.log(checkout.reference_id); // 这笔支付的唯一编号，请和订单一起保存
console.log(checkout.url);          // 把客户重定向到这里付款

三个必填字段是客户邮箱、客户编号和美元金额。返回的 url 是现成的付款页，reference_id 用于之后查询和对账。字段的完整说明见 API 对接教程。

3. 查询支付状态

const payment = await payram.payments.getPaymentRequest(checkout.reference_id);
console.log(payment.paymentState); // OPEN / FILLED / PARTIALLY_FILLED / OVER_FILLED / CANCELLED

各个状态的含义和处理方式，见 支付状态详解。

SDK 里还有出款相关的方法（payouts.createPayout、payouts.getPayoutById）。出款涉及审批和限额，是否开通以你的后台为准，流程见 退款与出款。

4. 接收 Webhook

SDK 为常见框架提供了现成的处理函数：Express、Fastify，以及 Next.js 的 App Router 和 Pages Router。它们会检查请求头、解析并校验载荷，并返回正确的响应，让 PayRam 知道你收到了。

import express from 'express';
import { Payram } from 'payram';

const app = express();
const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
});

app.post(
  '/payram/webhook',
  payram.webhooks.expressWebhook(async (payload, req) => {
    // 在这里处理事件，记得做幂等
    console.log('PayRam event:', payload.reference_id);
  }),
);

app.listen(3000);

Fastify 对应 fastifyWebhook，Next.js 的 App Router 对应 nextAppRouterWebhook。用法相同：传入一个异步处理函数。

5. 补上签名校验

官方文档里，SDK 的处理函数检查的是请求头 API-Key。而 Webhook 文档推荐的方式是 X-Payram-Signature：用项目 API 密钥对原始请求体做 HMAC-SHA256。后者还能保证请求体没有被篡改。

所以如果你想要签名校验，可以不用 SDK 的 Webhook 处理函数，自己写一个：拿到原始字节，按 Webhook 完全指南 里的方式校验，再处理事件。SDK 其余部分（创建支付、查询状态）照常使用。

6. 常见问题

SDK 能在浏览器前端里用吗？

不能，也不应该。它需要你的 API 密钥，而密钥只能放在服务器上。前端只负责把客户带到后端返回的 url。

不用 TypeScript 可以吗？

可以。直接调用 REST 接口即可，见 API 对接教程，里面有 curl、Node.js 和 Python 示例。

一个账号有多个项目怎么办？

每个项目有自己的 API 密钥。给每个项目创建一个客户端实例，用各自的密钥。见 多项目管理。

相关阅读

• API 创建支付：用 PayRam API 给自己的网站接加密货币收款：创建支付拿到付款链接，把客户引到支付页，用 Webhook 和状态接口确认到账，并用订单号对账。附 curl、Node.js、Python 示例。
• Webhook 完全指南：PayRam Webhook 怎么接：在后台添加回调地址，用 X-Payram-Signature 校验签名，理解重试规则与支付状态，做幂等处理，附 Node.js 和 Python 示例。
• 支付状态详解：PayRam 的五个支付状态是什么意思，少付（PARTIALLY_FILLED）、多付（OVER_FILLED）和过期（CANCELLED）该怎么处理，以及如何用 Webhook 和状态接口把订单状态对准。