Node.js / TypeScriptライブラリ
Node.jsアプリで暗号資産決済を受け付け
Node.jsサーバーから暗号資産の請求書を作成し、顧客をArionPayの支払いページに誘導して、支払い時に署名付きWebhookを検証します。資金はご自身のウォレットに直接届きます。
インストール
npm install arionpay例
機能
Node.js開発者向けArionPay
arionpayは、Node.js向けのArionPay公式クライアントです。請求書の作成と取得を行い、すべてのWebhookについて、信頼する前に生のボディで署名を検証します。
続きを読む
依存関係はなく、TypeScriptの型付きでESMとCommonJSのビルドを提供し、Node.js 18以降で動作します。ArionPayが資金を預かることはありません。各支払いはご自身のウォレットに直接届きます。- 依存関係なし。Node.js 18以降。
- ESMとCommonJSに対応し、TypeScriptの型定義付き。
- 請求書の各リクエストには冪等キーが付くため、ネットワークエラーで請求書が二重に作成されることはありません。初期設定では最大3回試行します(maxAttempts)。
- 請求書の各リクエストに、HMAC-SHA256とAPIシークレットで署名します。シークレット自体が送信されることはありません。
- 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の手数料は1回の支払いにつき0.5%で、月額料金はかかりません。
- ソースコード
- GitHubでオープンソース(MIT)として公開。
セットアップ
5つのステップで設定
ステップ1
パッケージをインストール
npm install arionpay を実行します。依存関係はありません。
ステップ2
キーをコピー
ArionPayダッシュボードでストアを開き、APIキー(pk_)とAPIシークレット(sk_。認証アプリのコードが求められます)をコピーします。Webhook署名シークレット(whsec_)は「Webhooks」ページにあります。3つともサーバー側に保管し、ブラウザのコードには決して含めないでください。
ステップ3
請求書を作成
金額、通貨、orderIdを指定してcreateInvoiceを呼び出し、顧客をinvoice.invoiceUrlにリダイレクトします。
ステップ4
Webhookを検証
「Webhooks」ページでWebhookアドレスを設定するか、請求書ごとにcallbackUrlで指定します。express.rawでボディを読み取ってverifyWebhookに渡し、invoice.paidで注文の商品を提供します。
ステップ5
実際のお金を使わずにテスト
test: trueとUSDT_TRC20などのassetを指定して請求書を作成し、simulatePayment(invoice.id, "exact")を呼び出します。実際の支払いと同じように、Webhookにinvoice.paidが届きます。
設定の後
支払いがコードに届くまで
- invoice.pending:ネットワーク上で支払いが検知され、承認を待っています。「お支払いを確認中」と表示してもかまいませんが、まだ商品を提供しないでください。
- invoice.paid:全額が支払われて承認された、またはあなたがダッシュボードで手動で受け付けたことを意味します。注文の商品の提供は、このイベントを受け取ったとき(またはgetInvoiceがpaidを返したとき)だけにしてください。顧客がsuccessUrlに戻ってきたことは、何の証明にもなりません。
- 商品を提供する前に、請求書を注文と照合してください。orderIdまたはmetadataが一致し、金額と通貨が注文の現在の合計と同じであることを確認します。
- invoice.partial、invoice.expired、invoice.needs_reviewは、どれも商品を提供してよいという意味ではありません。期限切れの請求書でも、遅れた支払いによって支払い済みになることがあります。
- ArionPayは、サーバーが2xxで応答するまで約3日間Webhookを再送するため、同じイベントが2回届くことがあります。event.idを使って、各イベントを1回だけ処理してください。
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.jsonではなくexpress.raw({ type: "application/json" })を使い、パースする前に検証してください。
いいえ。請求書の各リクエストには冪等キーが付くため、ネットワークエラーで請求書が二重に作成されることはありません。独自のidempotencyKeyを渡すこともできます。
はい。getInvoice(id)を呼び出し、statusが"paid"なら商品を提供します。Webhookと同じフィールド名を返すため、1つの関数で両方を処理できます。
ライブラリは無料のオープンソース(MITライセンス)です。ArionPayは各支払いの0.5%を前払いの手数料残高から差し引くため、全額がウォレットに届きます。月額料金や初期費用はなく、新規アカウントには$20分の手数料クレジットが付与されます。