跳到正文

Node.js / TypeScript 开发库

在您的 Node.js 应用中接受加密货币支付

从您的 Node.js 服务器创建加密货币账单,将客户引导至 ArionPay 支付页面,并在客户付款时校验签名 Webhook。资金直接进入您自己的钱包。

安装

npm install arionpay
GitHub 上的源代码
示例

功能介绍

面向 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. 第 1 步

    安装软件包

    运行 npm install arionpay。它没有任何依赖。

  2. 第 2 步

    复制您的密钥

    在您的 ArionPay 控制台中打开您的店铺,复制 API key(pk_)和 API secret(sk_,复制时需要输入验证器动态码)。Webhook 的 signing secret(whsec_)位于“Webhooks”页面。这三项都只能保存在您的服务器上,切勿放进浏览器代码。

  3. 第 3 步

    创建账单

    用金额、货币和您的 orderId 调用 createInvoice,然后将客户重定向到 invoice.invoiceUrl。

  4. 第 4 步

    校验 Webhook

    在“Webhooks”页面设置您的 Webhook 地址,或用 callbackUrl 为单张账单设置。用 express.raw 读取请求体,传给 verifyWebhook,并在收到 invoice.paid 时交付订单。

  5. 第 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。