---
title: "PHP SDK"
description: "Official KOMOJU PHP SDK client library for the KOMOJU Payments API, including session creation, webhook verification, and exception handling."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/sdks/php"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/sdks/php.md"
language: en
last_modified: "2026-06-26"
---

The KOMOJU PHP SDK is a full-featured PHP client for the KOMOJU Payments API, built on [Guzzle](https://github.com/guzzle/guzzle).

The source code is freely available on [GitHub](https://github.com/komoju/komoju-php-sdk). For a full reference of all available endpoints and models, see the [KOMOJU API Reference](https://docs.priv.staging.komoju-dev.tools/en/api-reference).

# Getting Started

Install the package via Composer.

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

```

Get your API keys from [KOMOJU Merchant Settings](https://komoju.com/merchant/settings) and configure the client.

```php
<?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](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-page-standard-mode.md).

## 1. Creating a Session

When your customer is ready to pay, create a session and redirect them to the returned `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. 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
<?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](https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/webhooks.md) to listen for payment events such as `payment.captured`, `payment.authorized`, and `payment.cancelled`. Configure your webhook URL in the [KOMOJU Merchant Dashboard](https://komoju.com/merchant/settings).

### Verifying Webhook Signatures

To ensure a webhook request genuinely came from KOMOJU, set a **secret token** when creating or updating the webhook. KOMOJU then signs every delivery with a SHA-256 HMAC of the raw request body in the `X-Komoju-Signature` header, which you can recompute and verify.

See [Webhooks → Secret Token](https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/webhooks.md#secret-token) for the full explanation and code examples.

# Error Handling

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

```php
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](https://github.com/komoju/komoju-php-sdk/issues).