ガイド
よくある質問Englishログイン

EC-CUBEをはじめる

概要

このガイドでは、EC-CUBEにKOMOJU決済プラグインを導入する手順を解説します。プラグインのインストール、APIキーの設定、決済方法の同期、Webhookの設定、本番公開前のテスト決済まで、ひととおりカバーします。

前提条件

✅
  • KOMOJUアカウント（未取得の場合はこちらから登録してください）
  • KOMOJUアカウントのLiveモード（本番環境）が利用可能な状態であること
  • EC-CUBEストアの管理者権限
  • EC-CUBE管理画面の基本操作に慣れていること
⚠️

このガイドは、Liveモードの利用申請が承認済みであることを前提としています。申請が審査中、もしくは未申請の場合は、先にLiveモード申請ガイドで手続きを済ませてください。

EC-CUBEとKOMOJUの連携の仕組み

KOMOJU決済プラグインは、対応するすべての決済方法を1つにまとめて管理します。インストールしてAPIキーを登録すれば、あとは管理画面から決済方法を同期するだけで導入完了です。

決済の流れは次のとおりです。

  1. 顧客がチェックアウト画面に進む
  2. 有効な決済方法が選択肢に表示される
  3. 決済方法を選ぶと、KOMOJUのホスト型決済ページへ遷移する
  4. KOMOJUが決済処理を行い、Webhookで通知を送る
  5. EC-CUBE側の注文ステータスが自動更新される
ℹ️

カード番号などの機密データは、EC-CUBEのサーバーを通りません。決済処理はすべて、PCI DSSに準拠したKOMOJU側の決済ページで完結します。

プラグインのインストール

ステップ 1: プラグインのダウンロード

KOMOJU決済プラグインの最新パッケージ（.tar.gz または .zip）を、公式リリースページからダウンロードします。

配布先は次のGitHubリポジトリです。

https://github.com/komoju/komoju-eccube/releases

ℹ️

お使いのEC-CUBEのバージョンに対応するファイルを選んでください。4.2以降向けと4.0〜4.1向けはパッケージが異なります。

ステップ 2: 管理画面からアップロードしてインストール

  1. EC-CUBE管理画面にログインします
  2. オーナーズストア → プラグイン → プラグイン一覧 を開きます
  3. ユーザー独自のプラグインをアップロードする（または「インストール」）をクリックし、先ほどダウンロードしたファイルをアップロードします
  4. アップロード後、プラグインを有効化します

有効化すると、左サイドメニューに KOMOJU決済 が表示されます。

KOMOJUアカウントとの連携

連携には、KOMOJU管理画面で取得したAPIキーを使います。

ステップ 1: API認証情報を取得する

  1. KOMOJU管理画面にログインします
  2. ID / API キー を開きます
  3. 次の3つの値をコピーします
    • クライアントID: アカウントの識別子
    • 非公開鍵 (Secret Key): サーバー側のAPI呼び出しで使用
    • 公開鍵 (Publishable Key): フロントエンドのトークン生成で使用

ステップ 2: EC-CUBEに認証情報を入力する

  1. EC-CUBE管理画面で KOMOJU決済 → 設定 を開きます
  2. APIキー設定 カードに、コピーした3つの値を入力します
  3. ページ下部の 保存 をクリックします

ステップ 3: 決済方法の同期

認証情報を保存したら、決済方法を更新 をクリックします。KOMOJUアカウントで利用可能な決済方法が取得され、設定ページにバッジ表示されます。

ℹ️

表示されるのは、KOMOJUアカウント側で有効化済みの決済方法だけです。

ステップ 4: 決済方法と配送方法の紐付け

EC-CUBEでは、各KOMOJU決済方法が個別の支払方法として登録されます。チェックアウトの選択肢に表示するには、決済方法ごとに最低1つの配送方法と紐付けてください。

  1. 設定 → 店舗設定 → 配送設定 を開きます
  2. 配送方法ごとに編集画面を開き、「支払方法の設定」でKOMOJUの決済方法にチェックを入れます
  3. 配送設定を保存します
⚠️

配送方法に紐付いていない決済方法は、プラグインで有効化していてもチェックアウト画面に出てきません。

Webhookの設定

Webhookを設定すると、KOMOJUで発生した決済イベント（売上確定、返金、キャンセルなど）がEC-CUBEに通知されます。設定しないと、注文ステータスは自動更新されません。

ステップ 1: Webhook URLとシークレットをコピーする

KOMOJU決済 → 設定 ページの Webhook設定 カードに、次の情報があります。

  • Webhookシークレット: コピーボタンで値をコピーできます
  • WebhookエンドポイントURL: KOMOJUからのイベント送信先URL

ステップ 2: KOMOJU管理画面でWebhookを登録する

  1. KOMOJU管理画面にログインします
  2. 管理 → Webhook を開きます
  3. EC-CUBEでコピーしたエンドポイントURLとシークレットを入力し、Webhookを新規登録します
  4. 次のイベントをすべて有効にします
    • payment.captured
    • payment.refunded
    • payment.cancelled
    • payment.expired
    • payment.failed
    • payment.updated
    • payment.authorized
⚠️

上記のイベントは、いずれもプラグインの動作に必要です。1つでも欠けると、注文ステータスが同期されないことがあります。

売上確定モードの設定

売上確定モードは、設定ページの 決済設定 カードで切り替えます。次の2種類から選べます。

  • 即時売上確定（オーソリ＆キャプチャ）: チェックアウト完了と同時に決済が確定（キャプチャ）されます。多くのストアに適したデフォルト設定です。
  • オーソリのみ: 仮売上（与信枠の確保）のみを行い、注文詳細ページから手動で確定するまで売上は計上されません。在庫確認や発送準備のあとに請求したい場合に便利です。
ℹ️

オーソリのみ を選んだ場合は、注文詳細ページから決済ごとに手動で売上確定してください。確定せずに放置すると、決済方法ごとの猶予期間を過ぎた時点で失効します。

なお、手動確定に対応していない決済方法は、この設定に関係なく自動で確定されます。

連携のテスト

本番公開の前に、決済フロー全体を一度通して動作確認してください。

ステップ 1: TESTモードに切り替える

KOMOJU管理画面を TESTモード に切り替え、テスト用のAPI認証情報（マーチャントUUID、非公開鍵、公開鍵）をコピーします。コピーした値をEC-CUBEのKOMOJU設定ページに貼り付けて保存します。

ステップ 2: テスト注文を実施する

顧客としてストアにアクセスし、チェックアウトから決済を完了させます。KOMOJUは、ほとんどの決済方法でテスト用のシミュレーション画面を提供しています。

クレジットカードのテストには、テストカードページのサンプル番号をご利用ください。

ステップ 3: 両方の管理画面で確認する

テスト決済が完了したら、両方の管理画面で結果を確認します。

  • EC-CUBE管理画面 → 受注管理: 注文が登録され、ステータスが更新されているか
  • KOMOJU管理画面 → 決済: 決済が「完了」または「オーソリ済み」で記録されているか
⚠️

ストア公開の前に、必ず Liveモード（本番環境） のAPI認証情報に切り替えてください。チェックアウト画面にはテストモードを示す表示は出ないため、切り替え忘れにご注意ください。

本番公開

実運用の準備が整ったら、次の手順で本番環境に切り替えます。

  1. KOMOJU管理画面で Liveモード に切り替えます
  2. 本番用のAPI認証情報をコピーします
  3. EC-CUBEの KOMOJU決済 → 設定 に貼り付けます
  4. 保存 をクリックし、続けて 決済方法を更新 で本番用の決済方法を同期します
  5. Liveモード環境でもWebhookが登録済みであることを確認します

まとめ

✅
  • KOMOJU決済プラグインのインストールと有効化
  • APIキーの登録と決済方法の同期
  • 決済方法と配送方法の紐付け
  • Webhookの登録による注文ステータスの自動更新
  • ストアに合わせた売上確定モードの選択
  • テスト決済による動作確認
  • Liveモードへの切り替え

Updated 2 days ago