---
title: "EC-CUBEをはじめる"
description: "EC-CUBEにKOMOJU決済プラグインをインストールし、認証情報の設定、決済方法の同期、Webhookの設定、テスト決済を行う手順です。"
url: "https://docs.komoju.com/ja/docs/integration-guides/ec-integrations/ec-cube/getting-started-with-ec-cube"
source_url: "https://docs.komoju.com/ja/docs/integration-guides/ec-integrations/ec-cube/getting-started-with-ec-cube.md"
language: ja
last_modified: "2026-07-10"
---

## 概要

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

> ⚠️ **Warning:** このガイドは、Liveモードの利用申請が承認済みであることを前提としています。申請が審査中、もしくは未申請の場合は、先に[Liveモード申請ガイド](https://help.komoju.com/hc/ja/articles/4747529679006-%E6%B1%BA%E6%B8%88%E6%89%8B%E6%AE%B5%E3%81%AE%E5%88%A9%E7%94%A8%E7%94%B3%E8%AB%8B%E6%96%B9%E6%B3%95-Live%E3%83%A2%E3%83%BC%E3%83%89%E7%94%B3%E8%AB%8B)で手続きを済ませてください。

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

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

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

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

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

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

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

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

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

[https://github.com/komoju/komoju-eccube/releases](https://github.com/komoju/komoju-eccube/releases)

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

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

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

## KOMOJUアカウントとの連携

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

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

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

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

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

![EC-CUBEのAPIキー設定](https://docs.komoju.com/eccube_getting-started_1.png)

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

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

![同期された決済方法](https://docs.komoju.com/eccube_getting-started_2.png)

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

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

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

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

![配送設定](https://docs.komoju.com/eccube_getting-started_3.png)

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

## Webhookの設定

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

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

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

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

![Webhook設定](https://docs.komoju.com/eccube_getting-started_4.png)

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

1. [KOMOJU管理画面](https://komoju.com/ja/sign_in)にログインします
2. **管理 → Webhook** を開きます
3. EC-CUBEでコピーしたエンドポイントURLとシークレットを入力し、Webhookを新規登録します
4. 次のイベントをすべて有効にします
- `payment.captured`
- `payment.refunded`
- `payment.cancelled`
- `payment.expired`
- `payment.failed`
- `payment.updated`
- `payment.authorized`

![Webhookイベントの選択 1](https://docs.komoju.com/ja_eccube_getting-started_5.png)

![Webhookイベントの選択 2](https://docs.komoju.com/ja_eccube_getting-started_6.png)

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

## 売上確定モードの設定

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

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

> ℹ️ **Note:** **オーソリのみ** を選んだ場合は、注文詳細ページから決済ごとに手動で売上確定してください。確定せずに放置すると、決済方法ごとの猶予期間を過ぎた時点で失効します。
>
> なお、手動確定に対応していない決済方法は、この設定に関係なく自動で確定されます。

## 連携のテスト

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

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

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

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

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

クレジットカードのテストには、[テストカード](https://docs.komoju.com/ja/docs/development/testing-inputs.md)ページのサンプル番号をご利用ください。

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

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

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

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

## 本番公開

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

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

## まとめ

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