タグを使った Stripe 取引データの自動連携

タグを使って Stripe の決済と Jolt のリードを自動で照合し、取引レコードの作成から紹介報酬の計算まで、一連の処理を自動化できます。

この記事について

Jolt では、Stripe 連携の基本設定に加えて、タグ（organization_id）を使ってリードと決済を自動照合するより精度の高い連携方法があります。

基本の Stripe 連携では、顧客 ID を手動で Jolt に登録する必要がありました。この記事の方法では、タグを通じて自動的に紐付けが行われるため、手動作業が不要になります。

	基本のStripe連携	この記事の方法（タグを使った連携）
顧客の紐付け方法	手動でStripe顧客IDを登録	タグ（organization_id）で自動照合
取引レコードの作成	自動	自動
前提条件	なし	タグによるリードステータス自動更新の設定が必要

前提条件

「タグを使ってリードステータスを自動更新する」の設定が完了していること

タグによる連携では、Stripe の決済と Jolt のリードを organization_id で照合します。設定で、ユーザーの organization_id が Jolt に登録されていることが前提です。

仕組みの全体像

ステップ	内容
①	ユーザーが有料プランに転換する
②	Stripe で決済が発生する
③	Stripe が Jolt に決済情報を通知する（Webhook）
④	Jolt がタグ（organization_id）をもとに、Stripe の決済と Jolt のリード／顧客を照合する
⑤	取引レコードを自動作成し、紹介報酬を自動で発生させる

設定手順

STEP 1：Jolt に Stripe を連携する

Jolt 管理画面のプログラム設定 > 連携設定 > アプリ連携 > Stripe から、Stripe 連携を有効にします。

💡 Stripe 連携の基本設定（Webhook URL の登録・署名シークレットの設定）がまだの場合は、先にStripe 連携についてを完了させてください。その際、STEP2で説明するイベントを追加で含めるようにしてください。

STEP 2：Stripe で受信イベントを追加する

Stripe の管理画面（開発者 > Webhook）で、既存の Webhook 設定を開き、以下のイベントが選択されていることを確認・追加してください。

イベント	用途
`charge.succeeded`	一回払いの決済完了
`invoice.paid`	サブスクリプションの月次請求完了
`charge.refunded`	返金

💡 基本のStripe連携では payment_intent.succeeded と charge.refunded を設定しています。タグ連携では charge.succeeded と invoice.paid を追加してください。

STEP 3：Stripe の顧客メタデータに `jolt_organization_id` を設定する

⚠️ ここがタグ連携の核心です。 この設定が漏れていると、Stripe での決済が Jolt のリードと紐付かず、紹介報酬が発生しません。

前提となる状況

この記事はすでに Stripe で決済が稼働しているサービスを運営している想定です。タグ連携を有効にした以降に新規発生する決済に対して、metadata.jolt_organization_id を自動付与する実装を追加します。

設定先は決済の種類によって異なる

Customer のメタデータに設定しても、タグ連携は機能しません。 Stripe の仕組み上、Webhook で送られてくるイベントには Customer のメタデータが含まれないためです。

決済の種類に応じて、以下のオブジェクトに設定してください。

決済の種類	受信されるイベント	metadata の設定先
一回払い	`charge.succeeded`	PaymentIntent
サブスクリプション	`invoice.paid`	Subscription

💡 Subscription の metadata は、毎月発行される Invoice に自動で引き継がれます。そのためサブスクの場合は Invoice ごとに設定する必要はなく、Subscription 作成時に1度設定すれば月次請求すべてに反映されます。

一回払いの場合：PaymentIntent に設定する

既存の paymentIntents.create 処理に metadata を1行追加します。

Before：

const paymentIntent = await stripe.paymentIntents.create({
  amount: amount,
  currency: 'jpy',
  customer: customerId,
});

After：

const paymentIntent = await stripe.paymentIntents.create({
  amount: amount,
  currency: 'jpy',
  customer: customerId,
  metadata: {
    jolt_organization_id: user.organizationId, // ← この1行を追加、変数を挿入してください
  },
});

サブスクリプションの場合：Subscription に設定する

既存の subscriptions.create 処理に metadata を1行追加します。

Before：

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
});

After：

const subscription = await stripe.subscriptions.create({
  customer: customerId,
  items: [{ price: priceId }],
  metadata: {
    jolt_organization_id: user.organizationId, // ← この1行を追加
  },
});

💡 上記のコード例は Node.js（公式SDK stripe-node）を使用していますが、Stripe が公式SDKを提供している他の言語（Ruby / Python / PHP / Go / .NET / Java）でも、同じく paymentIntents.create / subscriptions.create 相当のメソッドで metadata を渡せます。

既存のオブジェクトに後から追加する場合

すでに作成済みの PaymentIntent や Subscription に metadata を追加することもできます。

// PaymentIntent の場合
await stripe.paymentIntents.update(paymentIntentId, {
  metadata: { jolt_organization_id: user.organizationId },
});

// Subscription の場合
await stripe.subscriptions.update(subscriptionId, {
  metadata: { jolt_organization_id: user.organizationId },
});

organization_id の値の決め方

jolt_organization_id に入れる値は、「タグを使ってリードステータスを自動更新する」で Jolt に送信した organization_id と完全に同じ文字列である必要があります。

連携箇所	値の例
Jolt のタグ連携で送信する `organization_id`	`org_12345`
Stripe の metadata.jolt_organization_id	`org_12345`（同じ値）

実装上のポイント：自社DBで保持している組織IDなど、両方の連携で参照できる単一のソースから値を取得してください。

動作確認の方法

Stripeダッシュボードで確認

新規ユーザーで決済を1件発生させた後、Stripe の該当 PaymentIntent または Subscription のページを開く

「メタデータ」セクションに jolt_organization_id が表示されているか

値が Jolt の organization_id と一致しているか

Jolt 管理画面で照合確認

Jolt 管理画面の取引レコード一覧に、対象の取引が作成されているか

その取引が、想定通りのリード／顧客に紐付いているか

よくある実装ミス

ミス	結果	対処
Customer の metadata にだけ設定する	1段目の照合が機能しない（Stripe顧客IDフォールバックに落ちる）	PaymentIntent または Subscription に設定する
キー名を `organization_id` にしてしまう	照合に失敗（最終的にメールアドレスでフォールバック）	必ず `jolt_organization_id` を使う
`organization_id` を数値型で渡す	Stripeメタデータは文字列のみ。意図しない値になる可能性	文字列として渡す
サブスク利用なのに PaymentIntent にだけ設定	月次請求（Invoice）には引き継がれず照合失敗	Subscription に設定する
テスト環境で確認した `organization_id` の値のまま本番デプロイ	本番の `organization_id` と一致せず照合失敗	環境ごとに正しい値を流し込む

実装チェックリスト

リリース前に以下を確認してください。

一回払いを扱う場合：paymentIntents.create に metadata.jolt_organization_id を組み込んだ

サブスクリプションを扱う場合：subscriptions.create に metadata.jolt_organization_id を組み込んだ

metadata に渡している値が、Joltのタグ連携で送信している organization_id と同じソースから取得されている

テスト環境で新規ユーザーの決済を1件発生させ、Stripe側のオブジェクトにメタデータが付与されることを確認した

サブスクリプションを扱う場合：テスト環境で実際に請求を発生させ、生成された Invoice オブジェクトの metadata に jolt_organization_id が含まれていることを Stripe ダッシュボードで確認した

本番モードで新規ユーザーの決済を1件発生させ（テストモード不可）、Jolt に取引が作成され、正しいリードに紐付くことを確認した

顧客の照合ロジック

Stripe から決済情報が届いたとき、Jolt は以下の順番で対応する顧客を検索します。

優先順位	照合キー	説明
1	`jolt_organization_id`（PaymentIntent / Subscription のメタデータ）	推奨
2	Stripe 顧客 ID	基本のStripe連携と同じ方法（後方互換）
3	メールアドレス	最終フォールバック

💡 メールアドレスや Stripe 顧客 ID は変更されることがありますが、organization_id は変わりません。タグ連携を設定することで、より確実に照合できます。

取引が作成されたときの動作

照合に成功すると、以下が自動で実行されます。

取引レコードが Jolt に作成される

紹介プログラムの設定に従い、紹介報酬が計算・発生する

取引金額は Stripe の決済金額をそのまま使用される（一回払いは決済額、サブスクリプションは請求額）

返金時の動作

返金が発生すると、返金の種類に応じて自動で処理されます。

返金の種類	Jolt の動作
全額返金	取引レコードと報酬実績を削除する
部分返金	既存の取引を削除し、返金後の金額で取引を再作成・報酬を再計算する

■ よくある質問

Q. Stripe で決済が完了したのに、Jolt に取引が作成されません

A. 以下を順番に確認してください。

Stripe の Webhook 設定で、charge.succeeded / invoice.paid / charge.refunded が選択されているか

Stripe の PaymentIntent または Subscription のメタデータに jolt_organization_id が設定されているか

jolt_organization_id の値が、Jolt 管理画面のリード詳細に表示されている組織 ID と一致しているか

Q. サブスクリプションの場合、毎月自動で取引が作成されますか？

A. はい。請求が発生するたびに、取引レコードが自動で作成されます。

Q. 過去の決済は遡って取り込めますか？

A. できません。Webhook は設定以降に発生したイベントのみ受信します。

Q. 部分返金を複数回行った場合はどうなりますか？

A. 返金のたびに取引が再計算されます。最終的な取引金額は「元の金額 − 累積返金額」になります。