はじめに

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

composer require komoju-official/komoju-sdk

KOMOJU マーチャント設定から API キーを取得し、クライアントを設定します。

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

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

例: ホストページ決済

以下は、基本的なホストページ決済フローのサンプルです。詳細については、ホストページ実装ガイドをご参照ください。

1. Session の作成

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

<?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
$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 の設定を推奨します。Webhook URL は KOMOJU マーチャントダッシュボードから設定できます。

エラー処理

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

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

Issues

問題が発生した場合やフィードバックがあれば、GitHub よりご連絡ください。