結論
Stripe 決済をいちばん少ないコードで導入するなら Checkout(Stripe が用意する決済ページ)を使い、サーバーで Checkout セッションを作って返ってきた URL へ移動させ、支払いの完了は Webhook(checkout.session.completed)を署名つきで受け取って確かめます。開発中はサンドボックスのテスト用キー(sk_test_)と公式のテストカード 4242 4242 4242 4242 を使います。
この記事でわかること
- Payment Links・Checkout・Elements の違いと、日本の手数料の計算例
- Python の stripe ライブラリが実際に送る中身と、エラーの原文
- Webhook の署名を自分で計算して確かめた結果と、二重処理の防ぎ方
この記事で実際に動かしたもの:stripe ライブラリ 17.0.0 と Flask を入れた Python の仮想環境、127.0.0.1 で動かした自作の模擬 API サーバー、自作の秘密の値で署名した Webhook を受け取る Flask アプリです。本物の Stripe には一度も接続していません。
Checkout での支払いは、次の図のように「お店のサーバー」「Stripe の決済ページ」「Webhook」の3か所が関わります。支払いが終わったことを最終的に確かめるのは、右下の Webhook です。
flowchart TD
B[購入ボタン] --> S[自分のサーバー<br>Checkout セッション作成]
S -->|303 で移動| C[Stripe の決済ページ]
C -->|支払い後| R[success_url<br>完了画面]
C -.->|Webhook| W[自分のサーバー<br>署名を確認して発送・提供]
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| Stripe 決済とは | カード・コンビニ・PayPay などをネットで受け取れる決済サービス | Stripe 決済とは |
| 導入方法はどれを選ぶ | コードなしなら Payment Links、少ないコードなら Checkout、画面を作り込むなら Elements | 3つの違い |
| Stripe の手数料 | カードは成功ごとに 3.6%。初期費用・月額なし(2026年11月18日時点) | 手数料と計算例 |
| テストモードの使い方 | サンドボックスの sk_test_ キーで動かし、テストカードで払う | テストカード |
| テストカード番号 | 成功は 4242 4242 4242 4242、期限は未来の日付、CVC は任意の3桁 | テストカード |
| Python で Checkout | StripeClient の v1.checkout.sessions.create で作り、url へ 303 で移動 | Python で Checkout |
| Webhook の署名検証 | 未加工の本文・Stripe-Signature・whsec_ の秘密で construct_event | Webhook の受け取り |
| 返金のやり方 | refunds.create に payment_intent(一部なら amount も)を渡す | 返金・キャンセル |
確認環境:Ubuntu 24.04.5 LTS の上で、Python 3.13.18 の仮想環境に stripe 17.0.0(ライブラリが既定で送る API バージョンは 2026-10-28.endive)・Flask 3.1.3・requests 2.34.2 を pip で入れて動かしました。API の送り先は標準ライブラリの http.server で作った自作の模擬サーバー(127.0.0.1)で、Checkout セッションの作成・取得、返金、エラー応答を返す役です。Stripe のサーバーには一度も接続していません。Stripe へのログイン・アカウント作成・キーの発行もしていません。使ったキーは sk_test_ で始まる自作の文字列、Webhook の秘密も whsec_ で始まる自作の文字列で、実行は env -i で環境変数を空にした状態から行いました。模擬サーバーが返すエラーの文言は公式ドキュメントの形に合わせて自分で書いたもので、本物の応答そのものではありません(ライブラリが送る中身と、エラーを受けたときの例外の種類は本物です)。Stripe 公式のローカル用模擬サーバー stripe-mock は取得がプロキシに拒否されたため使っておらず、Stripe CLI もログインが要るため動かしていません(CLI の節は公式ドキュメントの記載です)。手数料・テストカード・Webhook の決まり・返金の条件は Stripe の公式サイト(docs.stripe.com・stripe.com/jp)で確かめました。図は mermaid で描画を確かめています(確認日 2026年11月18日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Stripe決済の導入方法|PythonでCheckoutとWebhook署名確認」
Stripe 決済とは(できることと支払い方法)
この節では、Stripe で何ができるのかと、日本で受け取れる主な支払い方法が分かります。
Stripe は、Web サイトやアプリでカードなどの支払いを受け取るための決済サービスで、API・決済ページ・管理画面(ダッシュボード)をまとめて提供しています。 カード番号はお店のサーバーを通らず Stripe の決済ページやフォームに入力されるため、お店の側はカード番号を持たずに支払いを受け取れます。
1一回きりの支払い
商品やサービスの代金を1回受け取る。Checkout では mode を payment にします。
2サブスクリプション
毎月などの継続の支払い。Checkout では mode を subscription にします(Billing は別料金)。
3カードの保存
今は請求せず、後で使う支払い方法を登録する。mode は setup です。
4返金・キャンセル
全額・一部の返金と、完了前の支払いの取り消し。ダッシュボードと API の両方でできます。
Stripe の日本の料金のページには、カードとウォレットのほか、コンビニ決済、PayPay、銀行振込の料金が並んでいます。どの支払い方法を出すかはダッシュボードの支払い方法の設定で切り替えられ、公式のクイックスタートには「カード決済とその他の一般的な支払い方法はデフォルトで有効化されます」とあります。
金額の書き方にも決まりがあります。日本円(JPY)は小数のない通貨なので、1,500 円なら unit_amount に 1500 をそのまま書きます。 米ドルのように小数2桁の通貨は 10 ドルを 1000 と書くので、通貨によって桁の扱いが変わる点に注意します。公式の通貨のページでは、日本円の最小の請求額は 50 円です。
Payment Links・Checkout・Elements の違い(どれで導入するか)
この節では、Stripe 決済の3つの導入方法の違いと、どれを選べばよいかが分かります。
Stripe の決済画面の作り方は、コードを書かない Payment Links、決済ページを Stripe に任せる Checkout、自分のページの中に入力欄を組み込む Elements の3つが中心です。 公式のオンライン決済のページは、ほとんどの実装に Checkout Sessions API を勧めています。
| 方法 | コード | 決済画面の場所 | 向いている用途 |
|---|---|---|---|
| Payment Links | 不要(ダッシュボードで作る) | Stripe の決済ページ(リンクを共有) | Web サイトがない・SNS やメールで売る・まず試す |
| Checkout(フルページ) | サーバーで数十行 | Stripe の決済ページへ移動(または埋め込み) | 自分のサイトの商品を売る。在庫・注文と連動させる |
| Checkout(埋め込みフォーム) | サーバーと画面の両方 | 自分のページの中(公開プレビュー) | ページを移動させたくない |
| Elements(Payment Element) | 画面とサーバーの両方で多め | 自分のページの中に入力欄を組み込む | 決済画面を細かく作り込みたい |
Checkout Sessions API に入っているもの
税金の計算(automatic_tax)・クーポン・送料
住所の入力・領収書・注文の概要
セッションは 24 時間で自動的に期限切れ
Payment Intents API で作る場合
税金・割引・送料・通貨の計算を自分で書く
画面は Elements のカスタムのみ
公式は「このパスの選択は慎重に」と案内
公式の注文処理(フルフィルメント)の説明には「Payment Links は Checkout を使う」とあり、Webhook の受け取り方は Payment Links と Checkout で同じです。そのため、Payment Links で始めて、あとから Checkout に移っても、受け取り側のコードはそのまま使えます。
Stripe の手数料(日本・2026年11月18日時点)と計算例
この節では、日本の Stripe の主な手数料と、金額ごとに実際にいくらになるかが分かります。
Stripe の日本の標準の料金体系では、カード決済は成功ごとに 3.6% で、初期費用と月額料金はありません。 以下は 2026年11月18日時点の stripe.com/jp の料金のページの記載です。
| 項目 | 手数料(公式の記載) | 補足 |
|---|---|---|
| カード・ウォレット | 3.6%(成功ごと) | 通貨換算が要る場合は +2% |
| コンビニ決済 | 3.6%(最低 ¥120) | 返金は ¥250 + 消費税10% |
| PayPay | 3.98% | デジタルコンテンツ事業向けは 9.48% |
| 銀行振込など | 1.5% | 返金は ¥250 + 消費税10% |
| 不審請求(チャージバック) | 1件 ¥1,500 | 申し立てを受けたときにかかる |
| Payment Links・Checkout | 受け付けは無料 | 独自ドメインは月 $10 |
| Billing・Tax | Billing は取引額の 0.7%、Tax は取引ごとに 0.5% など | サブスク・税の自動計算は別料金 |
この料率で、金額ごとの手数料を Python で計算しました(端数の扱いは公式の料金のページに記載がなかったため、小数のまま載せています)。
金額 | カード3.6% | 通貨換算あり(3.6%+2%) | コンビニ3.6%(最低120円) | PayPay3.98%
500 | 18.00 | 28.00 | 120.00 | 19.90
1,000 | 36.00 | 56.00 | 120.00 | 39.80
3,000 | 108.00 | 168.00 | 120.00 | 119.40
10,000 | 360.00 | 560.00 | 360.00 | 398.00
50,000 | 1800.00 | 2800.00 | 1800.00 | 1990.00
コンビニで最低手数料が3.6%を上回る境目: 3333.3333333333335
3000円を全額返金したときに戻らない手数料: 108.000
料金のページには「元の取引の決済処理手数料、Connect 手数料、通貨換算手数料は返金されません」とあります。標準の料金体系では、銀行振込などを除き返金そのものの手数料はかからないと書かれています。料金は変わることがあるので、導入の前に必ず公式の料金のページを見直します。
導入の流れと API キーの種類(サンドボックス・本番環境)
この節では、Stripe 決済を導入する順番と、API キーの種類・置き場所が分かります。
サンドボックスで作る
Stripe のアカウントを作り、ダッシュボードの「開発者」→「API キー」でサンドボックスのキーを確かめます。サンドボックスのキーは pk_test_・sk_test_・rk_test_ で始まります。
Checkout セッションを作るコードを書く
サーバーで金額・商品・戻り先の URL を決めてセッションを作り、返ってきた URL へ移動させます(次の節以降)。
Webhook を受け取る
支払いの完了を checkout.session.completed で受け取り、署名を確かめてから発送や提供を行います。
本番環境に切り替える
API キーのページで「サンドボックス環境」から「本番環境」に切り替え、pk_live_・rk_live_(または sk_live_)のキーと、本番の Webhook の署名シークレットに置き換えます。
| キー | 始まり | 画面に書いてよいか | 使う場所 |
|---|---|---|---|
| 公開可能キー | pk_test_ / pk_live_ | はい(公式が「安全に公開可能」) | ブラウザの Stripe.js・Elements |
| 制限付きキー | rk_test_ / rk_live_ | いいえ | サーバー。必要な権限だけ付ける(公式が推奨) |
| シークレットキー | sk_test_ / sk_live_ | いいえ | サーバー。すべての API を使える |
| Webhook 署名シークレット | whsec_ | いいえ | Webhook を受け取るサーバー。API キーとは別物 |
公式は、シークレットキーは権限を絞れないため新しい用途には勧めず、制限付きキーへの移行を勧めています。キーはソースコードや設定ファイルに書かず、ホスティングのシークレットの保管庫か環境変数で渡します。環境変数の扱い方は、関連記事「.envの使い方と注意点|APIキーを安全に管理する方法」で扱っています。
テストモード(サンドボックス)とテストカード番号
この節では、Stripe のテストモードの考え方と、公式のテストカード番号の使い分けが分かります。
Stripe のテストは、サンドボックスのテスト用 API キーと、公式のテストカード番号で行います。 公式ドキュメントは現在テスト用の環境を「サンドボックス」と呼び、新しい実装には「一般的なサンドボックス」を使うよう案内しています。検索でよく使われる「テストモード」は、このテスト用の環境を指す言い方です。サンドボックスと本番環境はキーもデータも別で、サンドボックスの商品を本番の決済に使うことはできません。
テストカードは、有効期限に未来の日付(公式の例は 12/34)、セキュリティコードに任意の3桁(American Express は4桁)を入れます。公式は、実際のカード情報をテストに使うことを利用規約で禁じていると説明しています。 次の番号は公式のテストのページの記載です。
| 試したいこと | カード番号 | 結果 |
|---|---|---|
| 支払いの成功(Visa) | 4242 4242 4242 4242 | 成功。3D セキュアは求められない |
| 日本のカード(Visa) | 4000 0039 2000 0003 | 成功(PaymentMethod は pm_card_jp) |
| 日本のカード(JCB) | 3530 1113 3330 0000 | 成功(pm_card_jcb) |
| 3D セキュアの認証 | 4000 0025 0000 3155 | 認証画面が出る |
| 一般的な拒否 | 4000 0000 0000 0002 | generic_decline |
| 残高不足で拒否 | 4000 0000 0000 9995 | insufficient_funds |
| 有効期限切れ | 4000 0000 0000 0069 | expired_card |
画面で入力して試すときはカード番号を、コードの自動テストでは pm_card_visa のようなテスト用の PaymentMethod を使うよう公式は勧めています。テスト API キーでは本番の決済は処理されません。
Python で Checkout セッションを作る(実際に送られた中身)
この節では、Python の stripe ライブラリで Checkout セッションを作るコードと、そのときライブラリが実際に送った HTTP の中身が分かります。
Checkout セッションは、サーバーで client.v1.checkout.sessions.create を呼んで作り、返ってきた url へ 303 で移動させます。 公式のクイックスタートの Python の例も StripeClient を使い、redirect(checkout_session.url, code=303) で移動させています。ライブラリは pip install stripe で入り、配布情報では Python 3.9 以上が必要でした。仮想環境の作り方は関連記事「Python venvの使い方|作成・有効化コマンド早見表と有効化できない時の直し方」にまとめています。
import os
from flask import Flask, redirect
from stripe import StripeClient
app = Flask(__name__)
client = StripeClient(
os.environ["STRIPE_SECRET_KEY"],
# 検証では模擬サーバーへ向けた。本番では STRIPE_API_BASE を設定しない
base_addresses={"api": os.environ.get("STRIPE_API_BASE", "https://api.stripe.com")},
)
DOMAIN = "http://127.0.0.1:4242"
@app.post("/create-checkout-session")
def create_checkout_session():
session = client.v1.checkout.sessions.create(params={
"mode": "payment",
"line_items": [{
"price_data": {"currency": "jpy", "unit_amount": 1500,
"product_data": {"name": "技術書(PDF)"}},
"quantity": 1,
}],
"success_url": DOMAIN + "/success?session_id={CHECKOUT_SESSION_ID}",
"cancel_url": DOMAIN + "/cart",
"metadata": {"order_id": "A-1002"},
})
return redirect(session.url, code=303)
このアプリを 127.0.0.1:4242 で起動し、curl で購入ボタンの代わりに POST した結果です。模擬サーバーが返した url へ 303 で移動する応答になりました。
$ curl -s -i -X POST http://127.0.0.1:4242/create-checkout-session
HTTP/1.1 303 SEE OTHER
Server: Werkzeug/3.1.9 Python/3.13.18
Content-Type: text/html; charset=utf-8
Location: https://checkout.stripe.com/c/pay/cs_test_a1000000000000000000000017
模擬サーバーの側で、ライブラリが送ったリクエストを記録しました(数量 2 で作り、続けて取得と返金を呼んだときのものです)。
POST /v1/checkout/sessions
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer sk_test_t644_dummy_not_real
Idempotency-Key: 0cb25122-2ddc-7c0e-8b7b-bbf966673e5d
Stripe-Version: 2026-10-28.endive
User-Agent: Stripe/v1 PythonBindings/17.0.0
body: mode=payment
line_items[0][price_data][currency]=jpy
line_items[0][price_data][unit_amount]=1500
line_items[0][price_data][product_data][name]=技術書(PDF)
line_items[0][quantity]=2
success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}
cancel_url=https://example.com/cart
metadata[order_id]=A-1001
GET /v1/checkout/sessions/cs_test_a1000000000000000000000003 ?expand[0]=line_items
Authorization: Bearer sk_test_t644_dummy_not_real
Stripe-Version: 2026-10-28.endive
見て分かることは3つです。本文は JSON ではなく、line_items[0][price_data][currency] のような角かっこの形のフォーム形式で送られます。 POST には毎回ランダムな Idempotency-Key(冪等キー)が自動で付き、GET には付きません。Stripe-Version にはライブラリが決めた API バージョンが入ります。
{CHECKOUT_SESSION_ID} は Stripe が戻るときにセッション ID に置き換える目印で、波かっこのまま送ります。金額はブラウザから受け取らず、サーバーの商品データで決めます。公式も「価格や在庫といった重要な情報は常に貴社のサーバーに置き、クライアント側から不正操作ができないようにします」と書いています。ダッシュボードで作った商品の価格 ID(price_ で始まる)を使う場合は、price_data の代わりに "price": "price_..." を渡します。
決済の完了は success_url ではなく Webhook で確かめる
この節では、支払いが終わったあとに商品を渡す処理(フルフィルメント)を、どこで行うべきかが分かります。
支払い完了の確かめ方
公式:「ランディングページに限定してフルフィルメントをトリガーすることはできません」
公式の注文処理のガイドは、fulfill_checkout という関数を1つ作り、Webhook と完了画面の両方から呼ぶ形を勧めています。そのうえで、この関数は「同じ Checkout セッション ID で複数回、場合によっては同時に呼び出される」ことがあるので、1回だけ処理されるように作るよう求めています。
| イベント | いつ届くか | すること |
|---|---|---|
| checkout.session.completed | 顧客が Checkout を終えたとき | payment_status が unpaid でなければ処理する |
| async_payment_succeeded(頭に checkout.session. が付く) | 銀行振込など、後から支払いが成功したとき | completed と同じ関数で処理する |
| async_payment_failed(同上) | 後からの支払いが失敗したとき | 顧客に連絡するなど |
完了画面では、URL の session_id でセッションを取得し、line_items を展開(expand)して中身を確かめます。模擬サーバーで取得したときの出力です。
s = client.v1.checkout.sessions.retrieve(session_id, params={"expand": ["line_items"]})
print(s.payment_status, s.payment_intent,
[(li.description, li.quantity, li.amount_total) for li in s.line_items.data])
paid pi_test_mock0001 [('技術書(PDF)', 2, 3000)]
公式によると、Webhook のエンドポイントで checkout.session.completed を受け取る設定にして success_url も指定した場合、Checkout はサーバーの応答を 10 秒待ってから顧客を移動させます。Webhook の処理が遅いと、そのぶん顧客を待たせることになります。
Stripe の Webhook の受け取りと署名の確認(Flask の実行結果)
この節では、Webhook を Flask で受け取り、署名を確かめるコードと、署名が合わないときに実際に出たエラーの原文が分かります。
Webhook は、未加工のリクエスト本文・Stripe-Signature ヘッダー・whsec_ で始まる署名シークレットの3つを stripe.Webhook.construct_event に渡して確かめ、失敗したら 400 を返します。 処理が重いときは先に 2xx を返し、重い処理は後に回すよう公式は勧めています。
import os, sqlite3, stripe
from flask import Flask, request, jsonify
app = Flask(__name__)
endpoint_secret = os.environ["STRIPE_WEBHOOK_SECRET"]
db = sqlite3.connect("orders.db", check_same_thread=False)
db.execute("CREATE TABLE IF NOT EXISTS events(id TEXT PRIMARY KEY)")
db.execute("CREATE TABLE IF NOT EXISTS fulfilled(session_id TEXT PRIMARY KEY, order_id TEXT)")
def fulfill_checkout(session):
if session["payment_status"] == "unpaid":
return "skip(unpaid)"
cur = db.execute("INSERT OR IGNORE INTO fulfilled VALUES(?,?)",
(session["id"], session["metadata"]["order_id"]))
db.commit()
return "fulfilled" if cur.rowcount == 1 else "already" # 2回目以降は処理しない
@app.post("/webhook")
def webhook():
payload = request.get_data() # 未加工の本文
sig_header = request.headers.get("Stripe-Signature")
try:
event = stripe.Webhook.construct_event(payload, sig_header, endpoint_secret)
except ValueError:
return jsonify(error="invalid payload"), 400
except stripe.SignatureVerificationError as e:
return jsonify(error=str(e)), 400
if db.execute("SELECT 1 FROM events WHERE id=?", (event["id"],)).fetchone():
return jsonify(received=True, note="duplicate"), 200
result = "ignored"
if event["type"] in ("checkout.session.completed",
"checkout.session.async_payment_succeeded"):
result = fulfill_checkout(event["data"]["object"])
db.execute("INSERT OR IGNORE INTO events VALUES(?)", (event["id"],)) # 処理が終わってから記録
db.commit()
return jsonify(received=True, type=event["type"], result=result), 200
このアプリに、自作の秘密の値で署名した checkout.session.completed のイベントを、条件を変えて送りました。/webhook-bad は、本文を request.get_json() で読んでから json.dumps で文字列に戻して検証する、よくある書き方を再現したものです。
1 正しい署名: 200 {"received":true,"result":"fulfilled","type":"checkout.session.completed"}
2 同じイベントをもう一度: 200 {"note":"duplicate","received":true}
3 本文を1文字変えた: 400 {"error":"No signatures found matching the expected signature for payload"}
4 別の秘密で署名: 400 {"error":"No signatures found matching the expected signature for payload"}
5 301秒前の署名: 400 {"error":"Timestamp outside the tolerance zone (1794976365)"}
6 290秒前の署名(別ID): 200 {"received":true,"result":"already","type":"checkout.session.completed"}
7 ヘッダーなし: 400 {"error":"No Stripe-Signature header value was provided. Read it from the incoming request's headers and pass it in; if this webhook has already been verified (or came from a trusted source), use one of the `*_without_verification` methods instead."}
8 v0だけ: 400 {"error":"No signatures found with expected scheme v1"}
9 JSONを読み直して検証: 400 {"error":"No signatures found matching the expected signature for payload"}
10 同じセッションの別イベント: 200 {"received":true,"result":"already","type":"checkout.session.async_payment_succeeded"}
9 の失敗の理由は、本文のバイト列が変わることです。受け取った本文(字下げつきの JSON)は 166 バイト、json.dumps(json.loads(...)) で戻した文字列は 130 バイトで、中身の意味が同じでも署名は一致しません。公式も「Stripe で署名の検証を実行するには、未加工のリクエスト本文が必要です」と書いています。 Express なら express.raw を使い、express.json() は Webhook のルートより後に置くよう公式は案内しています。
署名を確かめる本文
Flask は get_data、Express は express.raw、Django は request.body
署名の仕組みを自分で計算して確かめる
公式の「手動で Webhook の署名を検証する」の手順は、①ヘッダーを , で分けて t(タイムスタンプ)と v1(署名)を取り出す、②「タイムスタンプ + . + 本文」をつなげて signed_payload を作る、③署名シークレットを鍵に HMAC-SHA256 を計算する、④一定時間の比較で照らし合わせ、時刻のずれが許容範囲かを見る、の4つです。その手順どおりに署名を作り、ライブラリの生成した値と比べました。
import hmac, hashlib, time, stripe
def sign(payload: str, secret: str, ts: int) -> str:
signed_payload = f"{ts}.{payload}" # タイムスタンプ + "." + 本文
v1 = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
return f"t={ts},v1={v1}"
now = int(time.time())
h = sign(body, SECRET, now)
print("自作の署名ヘッダー:", h[:40] + "…")
print("ライブラリの生成と一致:", h == stripe.WebhookSignature.generate_signature_header(body, SECRET, now))
自作の署名ヘッダー: t=1794976655,v1=d699be5a91580a39acde1296…
ライブラリの生成と一致: True
許容範囲は、stripe ライブラリ 17.0.0 のソースでは DEFAULT_TOLERANCE = 300(秒)で、公式の「ライブラリには 5 分のデフォルトの許容範囲があります」と一致します。実行結果の 5(301秒前)が拒否され、6(290秒前)が通ったのはこのためです。公式は許容値に 0 を使わないよう注意しています(時刻の確認がまったく行われなくなるため)。サーバーの時計は NTP で合わせておきます。
ヘッダーには v1 のほか、テストのイベントにだけ v0 が付くことがあります。公式は v1 以外を無視するよう書いており、実行結果の 8 のとおり、ライブラリも v0 だけのヘッダーを受け付けません。Webhook の署名・再送・冪等性の一般的な考え方は、関連記事「Webhookとは?実装までわかる|署名検証・リトライ・冪等性を実行ログで解説」で扱っています。別のサービスの Webhook の署名の確認は、関連記事「Twilioとは|使い方・料金・日本のSMS規制とAPI・署名検証の実例」で扱っています。
二重処理を防ぐ(イベント ID と冪等キー)
この節では、Webhook が2回届いたときや、API の呼び出しを再試行したときに、二重に処理しない作り方が分かります。
Webhook は同じイベントが2回以上届くことがあるので、処理済みのイベント ID を記録し、記録があれば何もせず 200 を返します。 公式によると、本番環境では届かなかったイベントを指数バックオフで最長3日間再送し、サンドボックスでは数時間のうちに3回再送します。イベントが生成順に届く保証もありません。
この検証では、最初に書いたコードに落とし穴がありました。イベント ID を処理の前に記録していたため、処理の途中で例外が起きると 500 を返したのに ID だけが残り、2回目の配信では「duplicate」として処理されないまま終わりました。そのとき出た例外が次の原文です(stripe 17.0.0 では、イベントの中身は dict ではなく StripeObject なので .get() が使えません)。
AttributeError: 'get' is a dict method, but a StripeObject is not a dict. Use .to_dict() to convert it. Docs: https://github.com/stripe/stripe-python#working-with-api-resources
直したのは2点です。値の取り出しを session["metadata"]["order_id"] にし、イベント ID の記録を処理が終わったあとに移しました。さらに、発送の記録を Checkout セッション ID の一意制約で守っているので、completed と async_payment_succeeded のように別のイベントが同じセッションに届いても、実行結果の 10 のとおり2回目は「already」になります。
API を呼ぶ側の再試行も確かめました。模擬サーバーに 500 を返させ、StripeClient の max_network_retries を変えたときの送信回数です。
max_network_retries=None: 送信回数=1 間隔(秒)=[] 冪等キーの種類=1 最後=APIError 所要=0.00s
max_network_retries=0: 送信回数=1 間隔(秒)=[] 冪等キーの種類=1 最後=APIError 所要=0.00s
max_network_retries=2: 送信回数=3 間隔(秒)=[0.5, 0.54] 冪等キーの種類=1 最後=APIError 所要=1.04s
stripe 17.0.0 の StripeClient は、指定しなければ再試行しませんでした。2 を指定すると 0.5 秒前後の間隔で計3回送り、3回とも同じ冪等キーでした。公式は「再試行のデフォルト設定は、SDK、バージョン、クライアントの構築方法によって異なります」と書いているので、版を上げたら自分の環境で確かめます。冪等キーは少なくとも 24 時間保持され、その間に同じキーとパラメーターで送り直せば二重には作られません。二重課金を防ぐ設計全体は「冪等性とは?二重課金を防ぐ冪等キーとリトライ設計」で詳しく扱っています。
Stripe CLI でローカルテストする手順
この節では、公開 URL のない手元の PC で Webhook を受け取って試す、Stripe CLI の使い方が分かります(この節は公式ドキュメントの記載で、手元では動かしていません)。
入れる
macOS・Linux は curl -fsSL https://cli.stripe.com/install.sh | sh、Windows は PowerShell の irm https://cli.stripe.com/install.ps1 | iex。
自動更新が有効になる
ログインする
stripe login でペアリングコードが出て、Enter でブラウザが開きます。作られる API キーは 90 日間有効です。
アカウントとつなぐ
転送する
stripe listen --forward-to localhost:4242/webhook。表示される whsec_ の値を署名シークレットに使います。
ダッシュボードの秘密とは別
イベントを起こす
別のターミナルで stripe trigger payment_intent.succeeded。listen 側に [200 POST] などの結果が出ます。
再送は stripe events resend
公式の記載では、stripe listen を始めると Ready! Your webhook signing secret is '...' (^C to quit) と表示されます。CLI が表示する署名シークレットと、ダッシュボードで作ったエンドポイントの署名シークレットは別の値です。 公式は署名エラーのいちばん多い原因として、この取り違えを挙げています。
Stripe CLI を使わず、ngrok などで一時的な公開 HTTPS の URL を作ってダッシュボードに登録する方法も公式に書かれています。ngrok の使い方は関連記事「ngrokとは|使い方・料金・Webhook受信とエラーの直し方」にまとめています。本番の Webhook のエンドポイントは公開の HTTPS の URL で、TLS 1.2 か 1.3 に対応している必要があります。
Stripe の返金・キャンセルのやり方(API とダッシュボード)
この節では、全額・一部の返金と支払いのキャンセルの方法、返金が反映されるまでの目安が分かります。
返金は、ダッシュボードの「支払い」ページで対象の支払いのメニュー(⋯)から「支払いの返金」を選ぶか、API の refunds.create に payment_intent を渡して行います。 一部だけ返すときは amount を付けます。1つの支払いに複数回の返金ができますが、合計が元の金額を超えることはできません。
r = client.v1.refunds.create(params={
"payment_intent": "pi_test_mock0001",
"amount": 1500, # 3,000 円のうち 1,500 円だけ返す
"reason": "requested_by_customer",
})
print(r.id, r.status, r.amount, r.currency)
re_test_mock0001 succeeded 1500 jpy
| 状態(status) | 意味(公式の説明の要約) |
|---|---|
| pending | 返金の処理中 |
| succeeded | 顧客の銀行に入金される予定 |
| requires_action | コンビニ・銀行振込など、顧客の口座情報が要る返金で、メールの返事を待っている |
| failed | カードの解約などで返金できなかった(failure_reason に理由) |
| canceled | 返金を取り消した |
公式によると、顧客が返金を確認できるのは銀行によっておよそ 5〜10 営業日後です。支払いの直後に返金すると、返金ではなく「差戻し」として元の請求が明細から消える形になることがあります。返金は Stripe の利用可能な残高から行われ、足りないとカードの返金は保留されます。
支払いが完了する前であれば、PaymentIntent をキャンセルできます(手数料はかからないと公式に記載)。キャンセルできるのは、状態が requires_payment_method・requires_capture・requires_confirmation・requires_action などのときで、完了した PaymentIntent はキャンセルできず返金になります。
Stripe API のエラーの原文と、うまくいかないときの症状表
この節では、Stripe のライブラリが出す例外の種類と、よくあるつまずきの原因・直し方が分かります。
模擬サーバーに公式のエラーの形の応答を返させ、ライブラリがどの例外にするかを確かめました。例外の種類と http_status・code・param はライブラリが応答から作ったものです。
1 本番の形の鍵 -> AuthenticationError http_status=401 code=None param=None request_id=req_mock0007
Request req_mock0007: Invalid API Key provided: sk_live_****WXYZ
2 mode なし -> InvalidRequestError http_status=400 code=parameter_missing param=mode request_id=req_mock0008
Request req_mock0008: Missing required param: mode.
3 カード拒否 -> CardError http_status=402 code=card_declined param=None request_id=req_mock0009
Request req_mock0009: Your card has insufficient funds.
4 返金額が多い -> InvalidRequestError http_status=400 code=amount_too_large param=amount request_id=req_mock0010
5 429 -> RateLimitError http_status=429 code=None param=None request_id=req_mock0011
キーを環境変数に入れ忘れたときは、通信の前に手元で次のエラーになりました。
AuthenticationError: No API key provided. (HINT: set your API key using "client = stripe.StripeClient(<API-KEY>)"). You can generate API keys from the Stripe web interface. ...
エラーが出たときは、次の順に見ると原因にたどり着きやすくなります。
- 1例外の種類を見るAuthenticationError ならキー、InvalidRequestError ならパラメーター、CardError なら顧客側の支払い
- 2code と param を見るparameter_missing と param=mode なら mode の書き忘れ
- 3request_id でログを探すreq_ で始まる ID でダッシュボードのリクエストログを開く
- 4500・接続エラーは結果が不明として扱う同じ冪等キーで再試行するか、オブジェクトを取得して照合する
| 症状 | 原因 | 確かめ方 | 直し方 |
|---|---|---|---|
| Invalid API Key provided | キーの貼り間違い・期限切れ・サンドボックスと本番の取り違え | キーの先頭(sk_test_ / sk_live_) | ダッシュボードの API キーを貼り直す |
| No signatures found matching the expected signature for payload | 本文を読み直した・署名シークレットの取り違え | 受け取った本文のバイト数と whsec_ の値を出力する | 未加工の本文を渡す。CLI とダッシュボードの秘密を分ける |
| Timestamp outside the tolerance zone | サーバーの時計のずれ・送り直した本文を後で検証した | date とヘッダーの t= を比べる | NTP で時計を合わせる。受け取ってすぐ検証する |
| Webhook が 302 や 4xx で失敗 | リダイレクト・認証付きの URL・CSRF の保護 | ダッシュボードの「イベント配信」タブ | 最終の URL を登録し、Webhook のルートを CSRF の対象から外す |
| Webhook がタイムアウト | 応答の前に重い処理をしている | 処理時間をログに出す | 先に 2xx を返し、重い処理はキューに回す |
| 'get' is a dict method | StripeObject に dict のメソッドを使った | 例外の原文 | ["キー"] で読むか .to_dict() で変換する |
| 注文が2回処理された | 同じイベントの再送・別イベントが同じセッションに届いた | イベント ID とセッション ID のログ | 処理後に ID を記録し、セッション ID で一意にする |
| 1,500 円のつもりが違う金額 | 小数2桁の通貨の感覚で 100 倍した | currency と unit_amount | JPY は円の数そのまま(1500) |
Stripe 決済の導入方法の判断表と本番前の確認
この節では、状況ごとにどの方法を選ぶかと、本番に切り替える前に確かめることが分かります。
| 状況 | 選ぶもの | 理由 |
|---|---|---|
| サイトがない・まず売ってみたい | Payment Links | コードなしでリンクを作れる。受け取りの Webhook は Checkout と同じ |
| 自分のサイトで商品を売り、注文と連動させたい | Checkout(フルページ) | 公式が推奨。税・クーポン・領収書が入っている |
| ページを移動させたくない | Checkout の埋め込み | 同じ Checkout Sessions API で埋め込める(埋め込みフォームは公開プレビュー) |
| 決済画面を細かく作り込みたい | Elements | 入力欄を自分のページに組み込める。その分コードは多い |
| 毎月の請求をしたい | Checkout の mode=subscription | サブスクの作成が入っている(Billing は別料金) |
| Webhook を手元で試したい | Stripe CLI の stripe listen | 公開 URL なしで手元のサーバーに転送できる |
- 1キーを本番のものに替えたpk_live_ と rk_live_(または sk_live_)。コードに書かず保管庫か環境変数で渡す
- 2本番の Webhook のエンドポイントを登録した公開の HTTPS の URL。署名シークレットは本番のものに替える
- 3必要なイベントだけを受け取る設定にした全部を受け取るとサーバーの負荷が増える、と公式に記載
- 4同じイベント・同じセッションで2回処理されないイベント ID の記録とセッション ID の一意制約
- 5金額をサーバーで決めているブラウザから来た金額をそのまま使っていない
- 6返金・キャンセルの手順を決めたダッシュボードで誰が行うか、API で行うか
利用規約・特定の業種の扱い・個人情報の扱いなどは、導入の前に Stripe の最新の規約と案内、所属先の決まりを確かめます。
Stripe 決済の導入に関するよくある質問
この節では、Stripe 決済の導入でよく調べられる疑問への答えが分かります。
Q. Stripe の手数料はいくらですか?
日本の標準の料金体系では、カード決済は成功ごとに 3.6% で、初期費用・月額料金はありません。通貨換算が要る場合は +2%、コンビニ決済は 3.6%(最低 ¥120)、PayPay は 3.98% です(2026年11月18日時点の公式の料金のページ)。
Q. テストモードはどこで切り替えますか?
公式は現在、テスト用の環境を「サンドボックス」と呼んでいます。ダッシュボードのアカウントの切り替えで「サンドボックス」を選び、そのテスト用キー(sk_test_ など)を使います。本番に移るときは API キーのページで「本番環境」に切り替えます。
Q. テストカードの番号は?
成功は 4242 4242 4242 4242、日本の Visa は 4000 0039 2000 0003、JCB は 3530 1113 3330 0000 です。有効期限は未来の日付、セキュリティコードは任意の3桁を入れます。
Q. 支払いが終わったかは success_url で判断してよいですか?
公式は、完了画面だけで注文を処理しないよう書いています。顧客が画面を開く前に接続が切れることがあるためです。checkout.session.completed の Webhook で処理し、完了画面からも同じ関数を呼びます。
Q. Webhook の署名検証がずっと失敗します。
多い原因は、本文を JSON として読み直してから渡していることと、Stripe CLI の秘密とダッシュボードの秘密の取り違えです。この記事の検証では、読み直した本文は 166 バイトから 130 バイトに変わり、署名が一致しませんでした。
Q. 日本円の金額はどう書きますか?
日本円は小数のない通貨なので、1,500 円なら 1500 です。最小の請求額は 50 円と公式の通貨のページにあります。
Q. Python 以外の言語でも作れますか?
公式のクイックスタートには Node.js・Ruby・PHP・Java・Go・.NET の例があり、作るものは同じ Checkout セッションです。
Q. 返金はいつ顧客に届きますか?
公式によると銀行によっておよそ 5〜10 営業日です。返金しても元の取引の決済手数料は戻りません。
Q. Webhook が届かなかったときはどうなりますか?
本番環境では最長3日間、指数バックオフで再送されます。ダッシュボードからは作成後 15 日まで、Stripe CLI の stripe events resend では 30 日まで手動で再送できると公式に書かれています。
Q. 冪等キーは自分で付ける必要がありますか?
stripe ライブラリは POST に自動で付けていました(実測)。プロセスの再起動をまたいで再試行するなら、注文 ID などから作ったキーを保存して毎回同じ値を渡すよう公式は案内しています。
まとめ
- 少ないコードで導入するなら Checkout。コードなしなら Payment Links、作り込むなら Elements。受け取り側の Webhook は Payment Links と Checkout で同じ。
- 手数料はカード 3.6%(2026年11月18日時点)。3,000 円なら 108 円。返金しても元の手数料は戻らない。
- 開発はサンドボックスの sk_test_ キーとテストカードで。実際のカードはテストに使わない。キーはコードに書かない。
- 支払いの完了は Webhook で確かめる。未加工の本文・Stripe-Signature・whsec_ の秘密で construct_event。許容範囲は 5 分(ライブラリは 300 秒)。
- 二重処理を防ぐ。イベント ID は処理のあとに記録し、セッション ID で一意にする。API の再試行は同じ冪等キーで行われる。
参考・出典
- Stripe「料金体系(日本)」https://stripe.com/jp/pricing
- Stripe ドキュメント「オンライン決済」https://docs.stripe.com/payments/online-payments
- Stripe ドキュメント「Stripe がオンラインで提供する Checkout ページを作成」https://docs.stripe.com/checkout/quickstart
- Stripe ドキュメント「注文のフルフィルメント」https://docs.stripe.com/checkout/fulfillment
- Stripe ドキュメント「Webhook エンドポイントで Stripe イベントを受信する」https://docs.stripe.com/webhooks
- Stripe ドキュメント「イベントを設定する」「Webhook エンドポイントを管理する」https://docs.stripe.com/events/set-up-events・https://docs.stripe.com/events/manage-webhook-endpoints
- Stripe ドキュメント「導入内容をテストする(テストカード)」https://docs.stripe.com/testing
- Stripe ドキュメント「API キー」「サンドボックス」https://docs.stripe.com/keys・https://docs.stripe.com/sandboxes
- Stripe ドキュメント「支払いの返金とキャンセル」https://docs.stripe.com/refunds
- Stripe ドキュメント「エラー処理」「高度なエラー処理」https://docs.stripe.com/error-handling・https://docs.stripe.com/error-low-level
- Stripe ドキュメント「サポートされている通貨」https://docs.stripe.com/currencies
- stripe-python(GitHub)https://github.com/stripe/stripe-python
確認日:2026年11月18日
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Stripe決済の導入方法|PythonでCheckoutとWebhook署名確認」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。