The KOMOJU Node SDK is a full-featured TypeScript/JavaScript client for the KOMOJU Payments API. It works with any Node.js application or framework.

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:

npm install @komoju/komoju-sdk

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

import { Configuration, SessionsApi } from '@komoju/komoju-sdk';

const config = new Configuration();
config.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 sessionUrl.

const sessionsApi = new SessionsApi(config);

const session = await sessionsApi.createSession({
  createSessionRequest: {
    amount: 1000,
    currency: 'JPY',
    returnUrl: 'https://your-site.com/orders/return',
  },
});

res.redirect(session.data.sessionUrl);

2. Handling the Return URL

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

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

Fetch the session to check the outcome:

const { session_id } = req.query;

const result = await sessionsApi.showSession({ id: session_id });
const komojuSession = result.data;

if (komojuSession.status === SessionStatus.Completed) {
  // payment.status will be "captured", "authorized", or "pending"
  console.log(`Payment ${komojuSession.payment.status}`);
} else {
  console.log('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

API errors are thrown as exceptions with an HTTP status code and message.

try {
  const session = await sessionsApi.showSession({ id: 'sess_xxx' });
} catch (error) {
  console.error(error.response.status);   // e.g. 404
  console.error(error.response.data);     // error details
}

Issues

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