Stripe Node.jsとは？stripe-nodeライブラリの使い方とPAY.JPとの実装の違いを解説

Stripe Node.jsという言葉は、Node.js（サーバーサイドJavaScriptの実行環境）からStripeの決済機能を呼び出す際に、Stripe公式が提供するライブラリ「stripe-node」を使って実装することを指します。生のHTTPリクエストを自分で組み立てる代わりに、あらかじめ用意された関数を呼び出すだけで実装できるようになる点が特徴です。

この記事では、初めて決済を実装する方でも手を動かして再現できるよう、アカウント準備からコードの実行までを順を追って説明したうえで、国内の決済API「PAY.JP」のNode.js用ライブラリとの違いを解説します。

そもそも「Stripe Node.js」とは何を指すのか

Stripeの決済APIを実装する方法自体は、curlのようなコマンドで直接HTTPリクエストを送ることもできます。しかし実際の開発では、対応する言語ごとにStripeが公式に提供している「ライブラリ（SDK）」を使うのが一般的です。Node.js向けのライブラリがstripe-nodeで、npm（Node.jsのパッケージ管理ツール）経由でインストールして使います。

ライブラリを使う最大のメリットは、リクエストの組み立てやエラー処理といった定型的な処理があらかじめ用意されているため、実装量を減らせる点です。加えて、後述する自動リトライやTypeScriptの型定義など、生のHTTPリクエストでは自前で実装する必要がある機能も標準で備わっています。

事前準備：アカウントとテスト用キーを用意する

コードを書き始める前に、次の3点を用意します。

1. Node.jsのバージョンを確認する：ターミナルでnode -vを実行し、v18以上であることを確認してください（stripe-nodeはNode.js 18以上のLTS（長期サポート）バージョンに対応しています）
2. Stripeアカウントを登録し、テスト用のシークレットキーを取得する：Stripeのアカウント登録ページから登録すると、すぐに「テスト環境」が使えるようになります。ログイン後のダッシュボード（開発者向けのAPIキー画面）から、sk_test_から始まるテスト用シークレットキーを確認できます。このキーは実際のお金が一切動かないテスト環境専用です
3. 作業用フォルダでNode.jsのプロジェクトを準備する：任意のフォルダでnpm init -yを実行し、package.jsonを作成しておきます

stripe-nodeのインストールと基本的な使い方

準備ができたら、次のコマンドでstripe-nodeをインストールします。

npm install stripe

インストール後は、先ほど取得したテスト用シークレットキーを渡してクライアントを初期化し、各種APIを呼び出します。たとえば「顧客（Customer）」というデータを1件作成する場合は、次のように書きます（customer.jsのようなファイル名で保存し、node customer.jsで実行します）。

const stripe = require('stripe')('sk_test_...'); // 取得したテスト用シークレットキーに置き換える


stripe.customers
 .create({ email: 'customer@example.com' })
 .then((customer) => console.log(customer.id))
 .catch(console.error);

実行すると、作成された顧客のID（cus_から始まる文字列）がターミナルに表示されます。Stripeダッシュボードのテストデータを開くと、同じ顧客が一覧に追加されていることも確認できます。まずはこの「顧客を1件作る」という最小限の操作で、キー・ライブラリ・ネットワークがすべて正しくつながっているかを確認するのがおすすめです。

決済そのもの（金額を指定してカードから支払いを受け取る処理）は「PaymentIntent（決済の状態を表すオブジェクト）」、定期課金は「Subscription」という別の機能を使います。Stripe公式のAPIリファレンスには、これらの機能ごとの呼び出し方がNode.js向けのコード例付きで掲載されているため、実装時はこちらを参照するのが確実です。

なお、上記の例はrequireを使うCommonJS形式で書いていますが、import Stripe from 'stripe'というESM形式で書くことも可能です。その場合はpackage.jsonに"type": "module"を追加するか、ファイルの拡張子を.mjsにする必要がある点に注意してください（何も設定せずにimportを使うと、実行時に構文エラーになります）。

生のAPIリクエストとの違い：自動リトライ・TypeScript対応

stripe-nodeを使う具体的なメリットとして、次の2点が挙げられます。

• 自動リトライ機能：Wi-Fiの瞬断など、通信が一時的に失敗した場合に、既定で1回まで自動的にリトライする設定（maxNetworkRetries）が備わっています。この際、「Idempotency Key（同じ操作を再送しても二重に処理しないための仕組み）」がライブラリ側で自動的に付与されるため、開発者が個別に実装する必要がありません。リクエストごとに再試行回数を上書きすることも可能です

const stripe = require('stripe')('sk_test_...', {
 maxNetworkRetries: 2,
 timeout: 20 * 1000, // ミリ秒単位でタイムアウトを指定
});

• TypeScriptの型定義：TypeScript（型を指定できるJavaScriptの拡張言語）を使っている場合、Stripe.CustomerCreateParamsのようにリクエストパラメータやレスポンスの型があらかじめ用意されているため、パラメータ名の誤りや型の不一致をコード補完・コンパイル時に検知しやすくなります（TypeScriptを使わない場合はここは読み飛ばして問題ありません）

const params: Stripe.CustomerCreateParams = {
 email: 'customer@example.com',
};
const customer: Stripe.Customer = await stripe.customers.create(params);

PAY.JPでNode.jsから実装する場合の違い

国内の決済サービスPAY.JPにも、Node.js向けの公式ライブラリ「payjp-node」が用意されています（PAY.JPが提供するライブラリ一覧参照）。npmパッケージ名はpayjpで、インストール方法・基本的な呼び出し方はstripe-nodeと似た形です。

npm install --save payjp

顧客を1件作成する場合、Stripeの例とほぼ同じ形で書けます。

const payjp = require('payjp')('sk_test_...'); // PAY.JPのテスト用シークレットキーに置き換える


payjp.customers
 .create({ email: 'customer@example.com' })
 .then((customer) => console.log(customer.id))
 .catch(console.error);

PAY.JPのテスト用シークレットキーも、Stripeと同様にアカウント登録後、ダッシュボードから取得できます（テスト秘密鍵と本番秘密鍵について参照）。TypeScriptの型定義が提供されている点、タイムアウト時間を設定できる点も共通です。

なお、実際にカードで支払いを受け取る「決済（charge）」を作る場合は、カード番号をそのまま渡すのではなく、事前にトークン化（カード番号の代わりに使える一時的な引換券のような値に変換すること）したIDをcardパラメータに渡す形になります。この記事では割愛しますが、実装時はPAY.JPのドキュメントを参照してください。

一方、リトライ機能の考え方には違いがあります。payjp-nodeのリトライ（maxRetryオプション）は、アクセス過多によるHTTP 429（レート制限）エラーに対する再試行に特化した機能で、既定では無効になっており、必要に応じて有効にする設計です。これに対しstripe-nodeの自動リトライは、通信エラー全般を対象に既定で有効になっています。

どちらも「失敗時にどう再試行するか」を扱う機能ですが、対象範囲・既定値が異なるため、実装時はpayjp-nodeのドキュメント・Stripe API リファレンスそれぞれで挙動を確認してください。

Stripe決済全体の仕組みはStripeとは？決済プラットフォームの仕組み・機能・手数料でも解説しています。

PAY.JPとStripe、どちらが向いているか

ここまでの違いを実装者の視点で言い換えると、次のような目安になります。

• 「余計なことは自分で書きたくない」人にはStripeが向いている：通信エラー時の再試行やIdempotency Keyの付与を既定で肩代わりしてくれるため、初めて決済を実装する方や、AIコーディング支援を使ってスピーディーに実装したい方でも、失敗時の挙動を意識せずに済みます。加えて、他言語向けも含めた詳細なSDKバージョン管理ポリシーが公開されているなど、情報量・情報の新しさの面でも手厚いのが特徴です
• 「何が起きているかを自分で把握・制御したい」人にはPAY.JPが向いている：リトライは既定で無効になっており、必要な場面（レート制限エラー時など）だけ自分の意思で有効にする設計です。ライブラリが裏側で勝手に何かを再送することがないため、決済まわりの処理を細部まで自分で理解しながら実装したい方や、リクエスト数がそれほど多くなく自動リトライの恩恵が薄いケースでは、この振る舞いのシンプルさがかえって扱いやすい場合があります

どちらが優れているというより、「実装の手間を減らすことを優先するか」「挙動の予測しやすさ・シンプルさを優先するか」という好みの違いとして捉えるとよいでしょう。

まとめ

• 「Stripe Node.js」とは、Stripe公式のNode.js向けライブラリ「stripe-node」（npmパッケージ名stripe）を使ってStripeの決済機能を実装することを指す
• 実装を始めるには、Node.js 18以上・Stripeアカウントのテスト用シークレットキー・npm install stripeの3つを用意すればよく、顧客作成のような最小限のコードでキー・ライブラリの疎通を確認できる
• stripe-nodeは、生のHTTPリクエストに比べて、既定で有効な自動リトライ（Idempotency Keyの自動付与を含む）やTypeScriptの型定義といった機能を標準で備えている
• PAY.JPにもNode.js向けの公式ライブラリ「payjp-node」（npmパッケージ名payjp）があり、基本的な使い方やTypeScript対応は共通だが、リトライ機能の対象範囲・既定値は異なる
• 実装の手間を減らしたいならStripe、挙動のシンプルさ・自分での制御を重視するならPAY.JP、という選び方の目安になる
• PAY.JPのNode.js実装を実際に試してみたい方はPAY.JPのサービスページも確認してみてください