README

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

For a full reference of all available endpoints and models, see the KOMOJU API Reference.

Installation

Install the package via Composer.

composer require komoju-official/komoju-sdk:^1.0.0

Quick Start

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

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

Get your API keys from the KOMOJU Merchant Settings.

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.

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 for the full explanation and code examples.

Error Handling

All API errors throw Komoju\ApiException:

try {
    $payment = $paymentsApi->showPayment('pay_xxx');
} catch (Komoju\ApiException $e) {
    echo $e->getCode();       // HTTP status code (e.g. 404, 422)
    echo $e->getMessage();    // Human-readable description
    print_r($e->getResponseBody()); // Full response body
}

Documentation

Full API reference is auto-generated in the docs/ directory.

All URIs are relative to https://komoju.com/api/v1

Class	Method	HTTP request	Description
BarcodesApi	showBarcode	GET /barcodes/{payment_id}	Barcode: Show
ChargebacksApi	acceptChargebackRequest	POST /chargeback_requests/{id}/accept	Chargeback: Accept
ChargebacksApi	defendChargebackRequest	POST /chargeback_requests/{id}/defend	Chargeback: Defend
ChargebacksApi	listChargebackRequests	GET /chargeback_requests	Chargeback: List
ChargebacksApi	showChargebackRequest	GET /chargeback_requests/{id}	Chargeback: Show
DisbursementsApi	cancelDisbursement	POST /disbursements/{id}/cancel	Disbursement: Cancel
DisbursementsApi	createDisbursement	POST /disbursements	Disbursement: Create
DisbursementsApi	disbursementReport	GET /disbursements/report	Disbursement: Report
DisbursementsApi	listDisbursements	GET /disbursements	Disbursement: List
DisbursementsApi	showDisbursement	GET /disbursements/{id}	Disbursement: Show
EventsApi	listEvents	GET /events	Event: List
EventsApi	showEvent	GET /events/{id}	Event Show
OneClickApi	deleteExternalCustomer	DELETE /external_customers/{id}	External Customer: Destroy
PaymentsApi	cancelPayment	POST /payments/{id}/cancel	Payment: Cancel
PaymentsApi	capturePayment	POST /payments/{id}/capture	Payment: Capture
PaymentsApi	createPayment	POST /payments	Payment: Create
PaymentsApi	createRefundRequest	POST /payments/{id}/refund_request	Payment: Refund Request
PaymentsApi	finalizePayment	POST /payments/{id}/finalize	Payment: Finalize
PaymentsApi	listPaymentMethods	GET /payment_methods	Payment Method: List
PaymentsApi	listPayments	GET /payments	Payment: List
PaymentsApi	refundPayment	POST /payments/{id}/refund	Payment: Refund
PaymentsApi	showPayment	GET /payments/{id}	Payment: Show
PaymentsApi	updatePayment	PATCH /payments/{id}	Payment: Update
PlatformModelApi	balanceTransfer	POST /balances/{currency}/transfer	Balance: Transfer
PlatformModelApi	createFile	POST /merchants/{merchant_id}/files	File: Create
PlatformModelApi	createMerchant	POST /merchants	Merchant: Create
PlatformModelApi	createMerchantBalanceTransfer	POST /merchants/{merchant_id}/balances/{currency}/transfer	Balance: Transfer
PlatformModelApi	editMerchantBalanceSettings	PUT /merchants/{merchant_id}/balances/{currency}/settings	Balances: Edit Settings
PlatformModelApi	listLiveApplicationPaymentMethods	GET /live_application/{merchant_id}/payment_methods	Live Application: Payment Methods
PlatformModelApi	listMerchants	GET /merchants	Merchant: List
PlatformModelApi	listSubmerchantPayments	GET /merchants/{merchant_id}/payments	Payment: List for Merchant
PlatformModelApi	listSubmerchantSettlements	GET /merchants/{merchant_id}/settlements	Settlement: List
PlatformModelApi	merchantBalanceTransactions	GET /merchants/{merchant_id}/balances/{currency}/transactions	Balance: Transactions
PlatformModelApi	showFile	GET /merchants/{merchant_id}/files/{id}	File: Show
PlatformModelApi	showLiveApplication	GET /live_application/{merchant_id}	Live Application: Show
PlatformModelApi	showLiveApplicationPaymentMethod	GET /live_application/{merchant_id}/payment_methods/{payment_method}	Live Application: Show Payment Method
PlatformModelApi	showMerchant	GET /merchants/{id}	Merchant: Show
PlatformModelApi	showMerchantBalance	GET /merchants/{merchant_id}/balances/{currency}	Balance: Show
PlatformModelApi	showMerchantBalanceSettings	GET /merchants/{merchant_id}/balances/{currency}/settings	Balance: Show Settings
PlatformModelApi	showMerchantBalanceTransaction	GET /merchants/{merchant_id}/balances/{currency}/transactions/{transaction_uuid}	Balance: Transaction
PlatformModelApi	showSubmerchantSettlement	GET /merchants/{merchant_id}/settlements/{id}	Settlement: Show
PlatformModelApi	simulateLiveApplicationPaymentMethodStatus	PATCH /live_application/{merchant_id}/payment_methods/{payment_method}/simulate_status	Live Application: Simulate Payment Method Status
PlatformModelApi	simulateLiveApplicationStatus	PATCH /live_application/{merchant_id}/simulate_status	Live Application: Simulate Status
PlatformModelApi	submerchantSettlementCSV	GET /merchants/{merchant_id}/settlements/{id}/csv	Settlement: CSV
PlatformModelApi	submerchantSettlementPDF	GET /merchants/{merchant_id}/settlements/{id}/pdf	Settlement: PDF
PlatformModelApi	submerchantSettlementXLS	GET /merchants/{merchant_id}/settlements/{id}/xls	Settlement: XLS
PlatformModelApi	updateLiveApplication	PATCH /live_application/{merchant_id}	Live Application: Update
PlatformModelApi	updateLiveApplicationPaymentMethod	PATCH /live_application/{merchant_id}/payment_methods/{payment_method}	Live Application: Update Payment Method
PlatformModelApi	updateMerchant	PATCH /merchants/{id}	Merchant: Update
SecureTokensApi	createSecureToken	POST /secure_tokens	SecureToken: Create
SecureTokensApi	showSecureToken	GET /secure_tokens/{id}	SecureToken: Show
SessionsApi	cancelSession	POST /sessions/{id}/cancel	Session: Cancel
SessionsApi	createSession	POST /sessions	Session: Create
SessionsApi	paySession	POST /sessions/{id}/pay	Session: Pay
SessionsApi	showSession	GET /sessions/{id}	Session: Show
SettlementsApi	balanceTransactions	GET /balances/{currency}/transactions	Balance: Transactions
SettlementsApi	listSettlements	GET /settlements	Settlement: Index
SettlementsApi	showBalance	GET /balances/{currency}	Balance: Show
SettlementsApi	showSettlement	GET /settlements/{id}	Settlement: Show
SettlementsApi	showSettlementCSV	GET /settlements/{id}/csv	Settlement: CSV
SettlementsApi	showSettlementPDF	GET /settlements/{id}/pdf	Settlement: PDF
SettlementsApi	showSettlementXLS	GET /settlements/{id}/xls	Settlement: XLS
SettlementsApi	showTransaction	GET /balances/{currency}/transactions/{transaction_uuid}	Balance: Transaction
SubscriptionsApi	createCustomer	POST /customers	Customer: Create
SubscriptionsApi	createSubscription	POST /subscriptions	Subscription: Create
SubscriptionsApi	deleteCustomer	DELETE /customers/{id}	Customer: Destroy
SubscriptionsApi	deleteSubscription	DELETE /subscriptions/{id}	Subscription: Destroy
SubscriptionsApi	listCustomers	GET /customers	Customer: List
SubscriptionsApi	listSubscriptions	GET /subscriptions	Subscription: List
SubscriptionsApi	showCustomer	GET /customers/{id}	Customer: Show
SubscriptionsApi	showSubscription	GET /subscriptions/{id}	Subscription: Show
SubscriptionsApi	updateCustomer	PATCH /customers/{id}	Customer: Update
TokensApi	createToken	POST /tokens	Token: Create

Models

Authorization

Authentication schemes defined for the API:

api_key

Type: HTTP basic authentication (KOMOJU API key as username, blank password)
Use $config->setApiKey('YOUR_SECRET_KEY') for convenience

Support

KOMOJU Developer Documentation
KOMOJU Merchant Dashboard
For SDK issues, open an issue on GitHub

komoju-official / komoju-sdk

Maintainers

Package info

Statistics

Security