Ruby gem
在您的 Ruby 应用中接受加密货币支付
在您的 Rails、Sinatra 或 Rack 应用中创建加密货币账单,并在客户付款时校验签名 Webhook。资金直接进入您自己的钱包。
安装
gem install arionpay示例
功能介绍
面向 Ruby 开发者的 ArionPay
arionpay gem 是 ArionPay 官方的 Ruby 客户端,适用于 Ruby 3.0 或更高版本,仅使用标准库。它可以创建和读取账单,基于原始请求体校验 Webhook 签名,并能让测试账单经历各种付款场景。
阅读更多
账单是 Hash,字段名与 Webhook 相同,因此一个方法即可同时处理 Webhook 和查询结果。ArionPay 从不持有资金:款项直接进入您自己的钱包。- 无任何依赖(仅使用标准库)。Ruby 3.0 或更高版本。
- README 中提供 Rails、Sinatra 和纯 Rack 示例。Hanami 和普通脚本同样适用。
- 每个账单请求都带有幂等键,因此网络错误绝不会创建两张账单。
- verify_webhook 基于原始请求体校验签名;签名不匹配或超过 5 分钟时,会抛出 ArionPay::SignatureError。
- 交付前,ArionPay.order_matches?(invoice, "49.90", "USD") 会精确到分地核对订单总额。
- 客户端可以在多个线程之间安全共享(Puma、Sidekiq)。
- 参数错误会在发送任何内容之前抛出 ArgumentError。API 错误为 ArionPay::APIError,错误消息中绝不会包含您的密钥。
要求与许可证
- 适用于
- Ruby 3.0 或更高版本 · Rails、Sinatra、Hanami、任何 Rack 应用或普通脚本 · 仅使用标准库
- 费用
- 开发库免费。ArionPay 每笔付款收取 0.5% 手续费,无月费。
- 源代码
- 在 GitHub 上开源(MIT)。
设置
5 步完成设置
第 1 步
安装 gem
运行 gem install arionpay,或在您的 Gemfile 中加入 gem "arionpay"。
第 2 步
复制您的密钥
在您的 ArionPay 控制台中打开您的店铺,复制 API key(pk_)和 API secret(sk_,复制时需要输入验证器动态码)。Webhook 的 signing secret(whsec_)位于“Webhooks”页面。请将它们保存在环境变量或 Rails credentials 中。
第 3 步
创建账单
用 amount:、currency: 和 order_id: 调用 create_invoice,然后将客户重定向到 invoice["invoiceUrl"]。
第 4 步
校验 Webhook
在“Webhooks”页面设置您的 Webhook 地址,或用 callback_url: 为单张账单设置。将原始请求体(在 Rails 中为 request.raw_post)和 ArionPay-Signature 请求头传给 verify_webhook,并在收到 invoice.paid 时交付。
第 5 步
不用真钱进行测试
用 test: true 和 USDT_TRC20 等资产创建账单,然后调用 simulate_payment(invoice["id"], "exact")。您的 Webhook 会像真实付款一样收到 invoice.paid。
设置完成后
付款如何到达您的代码
- invoice.pending:已在网络上发现付款,正在等待确认。请暂勿交付。
- invoice.paid:已全额支付并确认,或由您在控制台中手动接受。只在收到此事件(或 get_invoice 显示 paid)时交付。返回 success_url 并不能证明已付款。
- 交付前,请将账单与您的订单核对:您的 order_id 或 metadata,并用 ArionPay.order_matches? 核对金额和货币。
- invoice.partial、invoice.expired 和 invoice.needs_review 都不代表可以交付。逾期付款仍可能让已过期的账单变为已支付。
- 如果您的服务器没有返回 2xx,ArionPay 会在大约 3 天内重复发送。每个 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 Ruby 开发库的问题
将它加入代码之前需要了解的简短解答。
支持。在基于 ActionController::API 的控制器中,或使用 skip_forgery_protection,将 request.raw_post 和 request.headers["ArionPay-Signature"] 传给 verify_webhook。捕获 ArionPay::SignatureError 并返回 401。
在 Rack 3 上,如果不先用 respond_to?(:rewind) 检查就调用 request.body.rewind,在某些服务器上(例如 WEBrick)会因 NoMethodError 而失败。请写成 request.body.rewind if request.body.respond_to?(:rewind)。
是的。一个客户端可以在多个线程之间安全共享,例如在 Puma 或 Sidekiq 中。
调用 ArionPay.verify_webhook(raw, header, webhook_secret)。它与客户端方法执行相同的校验。
该开发库免费开源(MIT 许可证)。ArionPay 从预付手续费余额中收取每笔付款的 0.5%,因此全额款项都会到达您的钱包。无月费,无开通费,新账户可获得 $20 手续费额度。