StripePayment プラグイン

🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

GP247/Shop のストアで Stripe による決済を受け付けます：国際カード、Apple Pay、Google Pay、Link、および Stripe アカウントで有効にした各地域の決済方法に対応します。お客様は Stripe の安全な決済ページで支払い、ストアに戻ります。 カード情報がお客様のサイトを経由することは一切ありません。

概要

機能

• 💳 Stripe Checkout — Stripe がホストする決済ページで、3-D Secure と電子ウォレットに標準対応しています。
• 🧾 注文への正確な入金記録 — Stripe が実際に回収した金額を、注文の支払い記録に正確に一度だけ記録します。お客様が サンクスページに戻る前にブラウザを閉じた場合も記録されます（Webhook による）。
• ↩️ 返金の同期 — Stripe Dashboard で行った一部返金・全額返金が注文に記録されます。
• 🧪 テストと本番 — スイッチ 1 つでテスト用キーと本番用キーを切り替えられます。
• 🏬 ストアごと — 各ストアで個別の Stripe アカウントを使うことも、サイト／マーケットプレイスのアカウントを共用することもできます。
• 🔒 安全 — Webhook は署名を検証します。secret key と webhook secret はデータベース内で暗号化されます。設定できるのは サイトオーナー／マーケットプレイスのオーナーだけです。
• 💱 正しい通貨単位 — VND、JPY などの「小数点のない」通貨は Stripe のルールに従って正しく送信されます。

支払いリンク（支払いリクエスト）

1.1.0 以降、支払いリクエスト画面を備えた gp247/shop では、Stripe でカート以外の代金も回収できます — 注文の残額、売掛金、手付金、自由な請求書など：

1. 管理者が 支払いリクエスト で回収のリクエストを作成し、支払いリンクを作成 をクリックして、リンクをお客様に送ります。
2. お客様はリンクを開いて Stripe を選び、Stripe のページで支払います。Stripe はお客様をリンクのページに戻し、入金完了のメッセージを表示します。
3. 代金はリクエストに正確に一度だけ記録されます（Webhook と戻りページが同時に届くことがあるため）。
4. 返金：回収済みの入金行で ゲートウェイ経由で返金 をクリックします（出金の権限が必要）。Stripe Dashboard で直接行った返金もリクエストに記録されます。

追加の設定は不要です。同じキーと同じ Webhook（下の章で登録したイベント）を使います。Stripe がリンクのページに表示されるのは、リクエストを所有するストアに secret key が設定されている場合のみです。代金は常にそのストアの Stripe アカウントに入金されます。

インストール

1. StripePayment フォルダーをサイトの app/GP247/Plugins/ にコピーします（または Admin → Extensions / Plugins → Import で ZIP ファイルをアップロードします）。
2. Admin → Extensions / Plugins を開き、Stripe を探して Install をクリックします。

プラグインはインストール後に有効になりますが、決済を受け付けられるのは Stripe のキー（下の章）を入力してからです。

設定

Admin → Plugins → Stripe を開きます（または一覧でプラグインをクリックします）。設定画面は 4 つのブロックに分かれており、 テスト用キーと本番用キーが混ざることはありません：

シークレットキーは保存時に暗号化され、画面に再表示されることはありません。各項目の下には 保存済み または 未設定 のラベルだけが表示されます。保存 をクリックするときにシークレット項目を空欄のままにすると、既存の値がそのまま保持されます。変更したい場合は新しい値を貼り付けてください。

Stripe キーの作成

環境ごとに 2 つのものが必要です：API key（決済セッションの作成用）と webhook signing secret（Stripe から 届く通知の検証用）です。Sandbox と Live は別々のセットで、一方の環境のキーをもう一方の環境で 使うことはできません。

まず Sandbox をひととおり設定し、決済が成功することを試してから Live を設定することをおすすめします。Live を使うには、Stripe アカウントが 有効化されている必要があります（事業者情報と入金先の銀行口座の登録）。

ステップ 1 — Stripe で正しい環境を選ぶ

1. dashboard.stripe.com にログインします。
2. アカウント切り替え（左上）で Sandboxes を選び、サンドボックスを開きます（まだなければ新規作成）。または Live 用にメインのアカウントのままにします。
3. 以下の手順はすべて選んだ環境の中で行います。Sandbox が終わったら、このステップに戻って Live を設定します。

ステップ 2 — API key を作成する

推奨：restricted key（プラグインに必要な権限だけを付与します。万一漏れても、悪用できることはほかにありません）。

1. API keys ページ（dashboard.stripe.com/apikeys）を開きます。
2. Create restricted key をクリックします。
3. Key name：分かりやすい名前を付けます。例：GP247 StripePayment – your-domain。
4. すべての権限を None のままにし、Checkout Sessions だけ Write を選びます。プラグインは決済セッションの作成と読み取りしか行わないため、 ほかの権限は不要です。
5. Create key をクリックし、Stripe からメール／SMS で届いた確認コードを入力します。
6. すぐにキーをコピーします（キーの値をクリック）。Live モードでは、自分で作成したキーは一度しか表示されません。コピーせずに 閉じてしまった場合は、別のキーを作成する必要があります。
7. 正しいブロックの Secret key 欄に貼り付けます：rk_test_… のキー → Sandbox ブロック、rk_live_… のキー → Live ブロック。

手早い方法：標準の secret key（sk_…、アカウントへのフル権限 — 安全性は劣ります）：API keys ページの Standard keys で、Secret key の行の Reveal をクリックしてコピーします。サンドボックスではいつでも再表示できます。Live で再表示できるのは Stripe があらかじめ作成したキーだけです。

ステップ 3 — Webhook を作成して signing secret を取得する

Webhook がないと、入金はお客様がサンクスページに戻ったときにしか記録されず、Stripe での返金も注文に反映されません。

1. GP247 の Stripe 設定画面で、モード ブロックの説明行にある Webhook URL をコピーします。形式は https://your-domain/plugin/stripe-payment/webhook です。
2. Stripe で Workbench → Webhooks（dashboard.stripe.com/webhooks）を開き、 Create an event destination をクリックします。
3. イベントのソースとして Your account を選びます。API バージョンはデフォルトのままにします。
4. 次の 6 つのイベントを正確に選びます：checkout.session.completed、checkout.session.async_payment_succeeded、 checkout.session.async_payment_failed、refund.created、refund.updated、refund.failed。
5. 送信先の種類として Webhook endpoint を選び、手順 1 の URL を Endpoint URL に貼り付けて作成します。
6. 作成したエンドポイントのページで、Signing secret の Reveal をクリックし、whsec_… の値をコピーします。
7. ステップ 2 の API key と同じブロック（Sandbox または Live）の Webhook signing secret 欄に貼り付け、保存 をクリックします。

Webhook には公開された HTTPS のアドレスが必要です。ご自身のパソコン（HTTPS なし）で試す場合は Stripe CLI を使います： stripe listen --forward-to http://localhost/plugin/stripe-payment/webhook — このコマンドが whsec_… のシークレットを表示するので、 それを Sandbox ブロックに貼り付けてください。

保存前のセルフチェック

• Sandbox ブロックには _test_ を含むキーだけ、Live ブロックには _live_ を含むキーだけが入っていること。
• 同じブロック内の API key と webhook secret は、Stripe の同じ環境から取得したものであること。
• テストモード のスイッチが使いたいブロックと一致していること（保存 後、そのブロックに 使用中 ラベルが表示されます）。

キーを安全に保つ

• キーをメール、チャット、スクリーンショットで送らないでください。設定画面に直接貼り付けるだけにしてください。
• キーの漏えいが疑われる場合：Stripe の API keys ページ → キーの ⋯ ボタン → Rotate key を実行し、新しいキーを GP247 に貼り付けます。Webhook secret も同様に、エンドポイントのページで Roll secret できます。

複数ストア／マーケットプレイス

• Multi-store：設定画面の上部でストアを選び、個別の Stripe キーを入力します。ドメインごとに別の Webhook エンドポイントを 登録し、エンドポイントごとに signing secret が異なります — 複数のストアが 1 つの Stripe アカウントを共用している場合でも、 そのシークレットを正しいストアに入力してください。
• マーケットプレイス：共通レベルでキーを入力します。空欄のままにした子ストアはマーケットプレイスのアカウントを使います。
• ストアごとの Stripe の有効／無効は プラグイン管理 画面で切り替えます。
• 子ストアの管理者とベンダーは、この設定画面を開けません。

決済のテスト

テストモード をオンにし、注文して Stripe を選び、テストカード 4242 4242 4242 4242、未来の任意の有効期限、 任意の CVC を使います。その他のテストカードは Stripe のドキュメント（Testing）を参照してください。

注意事項

• 通貨：注文の通貨は Stripe アカウントが対応しており、Stripe の最低金額（例：0.50 USD、 50 JPY）を満たしている必要があります。Stripe が拒否した場合、注文はキャンセルされ、在庫が戻り、お客様には別の支払い方法を選ぶよう案内されます。
• Stripe には注文合計と同額の「注文 #…」が1 行だけ表示されます（商品一覧は説明欄に入ります）。これにより、割引・税・送料がある場合でも 金額が常に注文と一致します。
• 返金は Stripe Dashboard で行います。Stripe から返金失敗の通知があった場合、注文にメモが残るので手動で対応してください。
• プラグインをアンインストールしても削除されるのはプラグインの設定だけで、注文に記録済みの入金・返金はそのまま残ります。

バージョン履歴

• 1.1.3 — Stripe 決済後（ストアへの戻り・キャンセル）の注文完了／キャンセルは、サイトが app/GP247/Shop/Controllers/ で ShopCartController を上書きしている場合、そのクラスを通して処理されるようになりました。独自の注文完了処理がスキップされなくなります。gp247_namespace() を備えた GP247 Core（3.1 以降）が必要です。
• 1.1.2 — プラグイン画面の日本語（日本語）翻訳を追加しました。
• 1.1.1 — 設定画面に 使用前チェック 枠を追加しました。お客様が Stripe で支払えない原因（チェックアウトで決済ステップが無効、ストアで Stripe が無効、使用中のモードの Secret key または Webhook signing secret が未入力、Stripe から Webhook URL に到達できない）と、サンドボックス中の注意を、それぞれの修正箇所とあわせて表示します。この枠を備えた GP247 Core が必要です。古い core では従来どおりの画面が表示されます。
• 1.1.0 — gp247/shop の 支払いリクエスト（支払いリンク /pay/…）について、リクエストを所有するストアのキーで Stripe による回収と返金ができるようになりました。この機能がない shop では、プラグインは 1.0.0 と同じように動作します。GP247 Core 3.1+ が必要です。
• 1.0.0 — 初回リリース：Stripe Checkout、署名付き Webhook、返金の同期、ストア別設定、シークレット キーの暗号化。