---
title: "PHP"
description: "GuzzleをベースにしたKOMOJU Payments API対応の公式PHP SDKの導入、セッション作成、Webhook検証、例外処理についてのガイドです。"
url: "https://docs.komoju.com/ja/docs/development/sdks/php"
source_url: "https://docs.komoju.com/ja/docs/development/sdks/php.md"
language: ja
last_modified: "2026-06-26"
---

KOMOJU PHP SDK は、[Guzzle](https://github.com/guzzle/guzzle) をベースにした KOMOJU Payments API 対応のフル機能 PHP クライアントです。

ソースコードは [GitHub](https://github.com/komoju/komoju-php-sdk) で公開しています。利用可能なエンドポイントやモデルの詳細については、[KOMOJU API リファレンス](https://docs.komoju.com/en/api-reference)をご参照ください。

# はじめに

Composer でパッケージをインストールします。

```bash
composer require komoju-official/komoju-sdk

```

[KOMOJU マーチャント設定](https://komoju.com/merchant/settings)から API キーを取得し、クライアントを設定します。

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';

$config = Komoju\Configuration::getDefaultConfiguration()
    ->setApiKey('YOUR_SECRET_KEY');

```

# 例: ホストページ決済

以下は、基本的なホストページ決済フローのサンプルです。詳細については、[ホストページ実装ガイド](https://docs.komoju.com/ja/docs/integration-guides/hosted-page-standard-mode.md)をご参照ください。

## 1. Session の作成

顧客が支払いの準備ができたら、Session を作成し、返された `session_url` にリダイレクトします。

```php
<?php
$sessionsApi = new Komoju\Api\SessionsApi(new GuzzleHttp\Client(), $config);

$session = $sessionsApi->createSession(
    new Komoju\Model\CreateSessionRequestWithPaymentMode([
        'mode'       => 'payment',
        'amount'     => 1000,
        'currency'   => 'JPY',
        'return_url' => 'https://your-site.com/orders/return',
    ])
);

header('Location: ' . $session->getSessionUrl());

```

## 2. Return URL の処理

顧客が支払いを完了すると、KOMOJU は `session_id` クエリパラメータを付加して `return_url` にリダイレクトします。

```
https://your-site.com/orders/return?session_id=xxxxx

```

Session を取得して結果を確認します。

```php
<?php
$sessionId = $_GET['session_id'];

$komojuSession = $sessionsApi->showSession($sessionId);

if ($komojuSession->getStatus() === Komoju\Model\SessionStatus::COMPLETED) {
    // payment status は "captured"、"authorized"、または "pending" になります
    echo 'Payment ' . $komojuSession->getPayment()->getStatus();
} else {
    echo '支払いがキャンセルまたは失敗しました';
}

```

## 3. Webhook の設定（推奨）

ステップ2のリダイレクトは、顧客がブラウザを閉じたりネットワーク障害が発生した場合に失敗することがあります。また、コンビニ払いのように支払いの確定が後になるケースもあります。これらに対応するため、`payment.captured`、`payment.authorized`、`payment.cancelled` などのイベントを受信する [Webhook](https://docs.komoju.com/ja/docs/introduction/webhooks.md) の設定を推奨します。Webhook URL は [KOMOJU マーチャントダッシュボード](https://komoju.com/merchant/settings)から設定できます。

### Webhook 署名の検証

Webhook リクエストが KOMOJU から送信されたものであることを確認するには、Webhook の作成または更新時に **secret token** を設定してください。KOMOJU はすべての配信において、リクエストボディの生データを使った SHA-256 HMAC 署名を `X-Komoju-Signature` ヘッダーに付加します。アプリケーション側で同じ署名を計算して照合することで、リクエストの正当性を検証できます。

詳細とコードサンプルは [Webhook → Secret Token](https://docs.komoju.com/ja/docs/introduction/webhooks.md#secret-token) をご参照ください。

# エラー処理

API エラーはすべて `Komoju\ApiException` としてスローされます。HTTP ステータスコード、メッセージ、レスポンスの詳細を取得できます。

```php
try {
    $session = $sessionsApi->showSession('sess_xxx');
} catch (Komoju\ApiException $e) {
    echo $e->getCode();              // HTTP ステータス (例: 404)
    echo $e->getMessage();           // エラーメッセージ
    print_r($e->getResponseBody());  // レスポンス詳細
}

```

# Issues

問題が発生した場合やフィードバックがあれば、[GitHub](https://github.com/komoju/komoju-php-sdk/issues) よりご連絡ください。