The KOMOJU PHP SDK is a full-featured PHP client for the KOMOJU Payments API, built on Guzzle.

The source code is freely available on GitHub. For a full reference of all available endpoints and models, see the KOMOJU API Reference.

Getting Started

Install the package via Composer.

composer require komoju-official/komoju-sdk

Get your API keys from KOMOJU Merchant Settings and configure the client.

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

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

Example: Hosted Page Payment

The following example walks through a basic hosted page payment flow. For a full guide, see the Hosted Page Integration Guide.

1. Creating a Session

When your customer is ready to pay, create a session and redirect them to the returned 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. Handling the Return URL

After the customer pays, KOMOJU redirects them back to your return_url with a session_id query param appended:

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

Fetch the session to check the outcome:

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

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

if ($komojuSession->getStatus() === Komoju\Model\SessionStatus::COMPLETED) {
    // payment status will be "captured", "authorized", or "pending"
    echo 'Payment ' . $komojuSession->getPayment()->getStatus();
} else {
    echo 'Payment was cancelled or failed';
}

3. Set Up Webhooks (Recommended)

It is possible that the redirect in step 2 fails, possibly due to the user closing their browser, network issues, etc. Or, that the capture will only take place later on, such as with Convenience Store payments. To account for this, we recommend setting up a Webhook to listen for payment events such as payment.captured, payment.authorized, and payment.cancelled. Configure your webhook URL in the KOMOJU Merchant Dashboard.

Error Handling

All API errors throw Komoju\ApiException. The exception exposes the HTTP status code, a message, and the full response body.

try {
    $session = $sessionsApi->showSession('sess_xxx');
} catch (Komoju\ApiException $e) {
    echo $e->getCode();              // HTTP status (e.g. 404)
    echo $e->getMessage();           // Human-readable description
    print_r($e->getResponseBody());  // Full response body
}

Issues

If you run into any problems or have feedback, feel free to open an issue on GitHub.