プラットフォームオンボーディングガイド

本ガイドでは、Jammにプラットフォームとして登録し、最初のAPIコールを行うまでの手順を説明します。

オンボーディングの流れ

1. アカウントの作成: ステップ1。 プラットフォームアカウントはJammチームが作成します。開始するには、以下の情報をご提供ください：

   • プラットフォーム名

   • 連絡先メールアドレス

   • 入金モードの希望: 一括入金（PLATFORM）またはダイレクト（MERCHANT）— 詳細についてはPayout Guideを参照してください。

   • 入金スケジュールの希望: 月次（EVERY_MONTH）または月2回（TWICE_PER_MONTH）

   • 銀行口座情報（一括入金モードの場合は必須）：

     • 銀行番号
     • 支店番号
     • 口座番号
     • 預金種別
     • 受取人名

     JammがプラットフォームアカウントをJammが作成し、プラットフォームID（plt-*）を発行します。

2. 加盟店の連携: ステップ2。 加盟店の代理として操作を行うには、事前に加盟店をプラットフォームに連携する必要があります。加盟店をオンボーディングするには、加盟店ごとに1行のCSV/ExcelシートをJamm Opsチームと共有してください。

   CSVテンプレート

   name,email,phone,platform_merchant_webhook_url,bank_number,branch_number,account_number,deposit_type,recipient_name
   Sample Shop One,owner1@example.com,09011112222,,,,,,
   Sample Shop Two,owner2@example.com,09011112223,https://example.com/webhook,0001,001,1234567,普通,サンプル ショップ

カラム一覧

注: 銀行口座カラムは、プラットフォームがダイレクト（MERCHANT）入金モードを使用する場合のみ必要です — 一括入金（PLATFORM）モードでは、ステップ1で設定したプラットフォームの銀行口座に入金されます。提供する場合、5つの銀行口座カラムすべてを入力する必要があります（全部または無し）。APIによる加盟店の自動オンボーディングは近日公開予定です。

3. 認証情報の受け取り: ステップ3。 Jammがプラットフォーム用の認証情報を発行します。以下を受け取ります：

   • クライアントID

   • クライアントシークレット

     環境ごとに別々の認証情報が発行されます。認証情報、データ、Webhook設定は各環境間で完全に分離されています。

     項目	ステージング	本番
     用途	開発・テスト	本番運用
     ダッシュボード	https://dashboard.staging.jamm-pay.jp	https://dashboard.jamm-pay.jp
     認証情報	ステージング専用クライアントID / シークレット	本番専用クライアントID / シークレット
     データ	テストデータのみ。実際の入出金は発生しません。	実データ。実際の資金移動が発生します。

     セキュリティ上の注意: 認証情報は安全に管理してください。クライアントサイドのコードには絶対に含めないでください。

4. インストールと設定: ステップ4。 Jamm Node SDKをインストールします：

   npm install @jamm-pay/node-sdk

認証情報を使って初期化します。platform: trueフラグは、（単一の加盟店ではなく）プラットフォームとして認証することをSDKに伝えます：

   import jamm from "@jamm-pay/node-sdk";

   jamm.config.init({
     clientId: process.env.JAMM_CLIENT_ID,
     clientSecret: process.env.JAMM_CLIENT_SECRET,
     environment: process.env.JAMM_ENVIRONMENT as "staging" | "prod",
     platform: true,
   });

.env（ステージング）

JAMM_CLIENT_ID=your-staging-client-id
JAMM_CLIENT_SECRET=your-staging-client-secret
JAMM_ENVIRONMENT=staging

SDKが認証（トークンの交換と更新）を自動で処理します。

5. 最初の決済を行う: ステップ5。 オンセッション決済を作成します。merchantオプションで、代理として操作する加盟店を指定します：

   const result = await jamm.payment.onSessionPayment({
     buyer: {
       email: "customer@example.com",
     },
     charge: {
       price: 10000,
       description: "注文 #1234",
       platform_fee: 500,   // 任意 — 下記の注意事項を参照
       metadata: {},        // 任意のキーと値のペア（独自の管理用）
     },
     redirect: {
       successUrl: "https://yoursite.com/success",
       failureUrl: "https://yoursite.com/failure",
     },
     merchant: "mer-abc123",
   });

   // 決済完了のために顧客をリダイレクト
   const paymentUrl = result.data?.paymentLink?.url;

   // 今後の請求のために顧客IDを保存
   const customerId = result.data?.customer?.id; // "cus-..."

注: リクエストのbuyerフィールドは顧客レコードを作成または照合します。platform_feeはダイレクト入金モード（MERCHANT）でのみ有効であり、加盟店の入金から控除される金額を制御します。一括入金モード（PLATFORM）では省略可能です。詳細については、プラットフォーム手数料を参照してください。

6. Webhookの設定: ステップ6。 Jammは決済イベントの通知を、指定されたWebhook URLに送信します：

   import jamm from "@jamm-pay/node-sdk";

   jamm.webhook.verify({
     data: body,
     signature: body.signature,
   });

   const event = jamm.webhook.parse({ data: body });

   if (jamm.types.eventTypeEquals(jamm.types.EventType.CHARGE_SUCCESS, event.eventType)) {
     // 決済成功 — 注文を処理する
   }

イベントタイプ

本番稼働前チェックリスト

本番稼働前に以下を確認してください：

• プラットフォームアカウントが作成され、有効化されている
• すべての加盟店が連携されている
• 本番認証情報で認証が正常に動作する
• すべてのリクエストに加盟店IDが正しく設定されている（SDKのmerchantオプション）
• 各請求にplatform_feeが設定されている（ダイレクト入金モードを使用する場合）
• 決済フローがエンドツーエンドでテスト済み（決済作成、顧客による完了、Webhook受信）
• 返金フローがテスト済み（全額および部分返金）
• Webhookエンドポイントが設定され、両環境でイベントを受信している
• Webhook署名検証が正常に動作している
• 入金用銀行口座情報がJammチームと確認済み

近日公開予定

• セルフサービス加盟店オンボーディング — Jammチームに連絡せず、APIで加盟店を追加
• 審査付きオンボーディング — Jammが各加盟店を有効化前に審査する必要があるプラットフォーム向け
• プラットフォームダッシュボード — 加盟店の管理、取引の確認、入金レポートのダウンロード