Node.js / TypeScript 开发库
在您的 Node.js 应用中接受加密货币支付
从您的 Node.js 服务器创建加密货币账单,将客户引导至 ArionPay 支付页面,并在客户付款时校验签名 Webhook。资金直接进入您自己的钱包。
安装
npm install arionpay示例
功能介绍
面向 Node.js 开发者的 ArionPay
arionpay 是 ArionPay 官方的 Node.js 客户端。它可以创建和读取账单,并在您信任每个 Webhook 之前,基于原始请求体校验其签名。
阅读更多
它没有任何依赖,提供 ESM 和 CommonJS 构建以及 TypeScript 类型定义,可在 Node.js 18 或更高版本上运行。ArionPay 从不持有资金:每笔付款都直接进入您自己的钱包。- 无任何依赖。Node.js 18 或更高版本。
- 支持 ESM 和 CommonJS,含 TypeScript 类型定义。
- 每个账单请求都带有幂等键,因此网络错误绝不会创建两张账单。默认最多尝试 3 次(maxAttempts)。
- 使用 HMAC-SHA256 和您的 API secret 为每个账单请求签名,密钥本身从不发送。
- verifyWebhook 基于原始请求体校验 ArionPay-Signature 请求头;签名不匹配或超过 5 分钟时,会抛出 ArionPaySignatureError。
- simulatePayment 可让测试账单经历 exact、underpaid_1pct、overpaid 或 late 等场景,sendTestWebhook 则会发送一个签名的示例事件。
- 错误为 ArionPayError,包含 HTTP 状态码和 rate_limited、unknown_asset 等错误代码。错误消息中绝不会包含您的密钥。
要求与许可证
- 适用于
- Node.js 18 或更高版本 · Express、Next.js(App Router)· ESM、CommonJS 和 TypeScript 类型定义
- 费用
- 开发库免费。ArionPay 每笔付款收取 0.5% 手续费,无月费。
- 源代码
- 在 GitHub 上开源(MIT)。
设置
5 步完成设置
第 1 步
安装软件包
运行 npm install arionpay。它没有任何依赖。
第 2 步
复制您的密钥
在您的 ArionPay 控制台中打开您的店铺,复制 API key(pk_)和 API secret(sk_,复制时需要输入验证器动态码)。Webhook 的 signing secret(whsec_)位于“Webhooks”页面。这三项都只能保存在您的服务器上,切勿放进浏览器代码。
第 3 步
创建账单
用金额、货币和您的 orderId 调用 createInvoice,然后将客户重定向到 invoice.invoiceUrl。
第 4 步
校验 Webhook
在“Webhooks”页面设置您的 Webhook 地址,或用 callbackUrl 为单张账单设置。用 express.raw 读取请求体,传给 verifyWebhook,并在收到 invoice.paid 时交付订单。
第 5 步
不用真钱进行测试
用 test: true 和 USDT_TRC20 等资产创建账单,然后调用 simulatePayment(invoice.id, "exact")。您的 Webhook 会像真实付款一样收到 invoice.paid。
设置完成后
付款如何到达您的代码
- invoice.pending:已在网络上发现付款,正在等待确认。可以显示“付款正在途中”,但请暂勿交付。
- invoice.paid:已全额支付并确认,或由您在控制台中手动接受。只在收到此事件(或 getInvoice 显示 paid)时交付订单。客户回到 successUrl 什么也证明不了。
- 交付前,请将账单与您的订单核对:您的 orderId 或 metadata,以及与订单当前总额相同的金额和货币。
- invoice.partial、invoice.expired 和 invoice.needs_review 都不代表可以交付。逾期付款仍可能让已过期的账单变为已支付。
- 在您的服务器返回 2xx 之前,ArionPay 会在大约 3 天内重复发送 Webhook,因此同一事件可能到达两次。请用 event.id 确保每个事件只处理一次。
9 个网络上的 16 种币和代币
全部币种- BTCBitcoin
- ETHEthereum
- USDTEthereum
- USDCEthereum
- BNBBNB Smart Chain
- USDTBNB Smart Chain
- USDCBNB Smart Chain
- POLPolygon
- USDTPolygon
- USDCPolygon
- TRXTRON
- USDTTRON
- LTCLitecoin
- DOGEDogecoin
- BCHBitcoin Cash
- DASHDash
关于 ArionPay Node.js 开发库的问题
将它加入代码之前需要了解的简短解答。
可以。在 App Router 路由中,用 await request.text() 读取请求体,并连同 arionpay-signature 请求头和您的 Webhook 密钥一起传给 verifyWebhook。
签名覆盖的是 ArionPay 发送的原始字节。请在 Webhook 路由上使用 express.raw({ type: "application/json" }),而不是 express.json,并在解析之前先校验。
不会。每个账单请求都带有幂等键,因此网络错误绝不会创建两张账单。您也可以传入自己的 idempotencyKey。
可以。调用 getInvoice(id),并在其状态为“paid”时交付。它返回的字段名与 Webhook 相同,因此一个函数即可同时处理两者。
该开发库免费开源(MIT 许可证)。ArionPay 从预付手续费余额中收取每笔付款的 0.5%,因此全额款项都会到达您的钱包。无月费,无开通费,新账户可获得 $20 手续费额度。