KOMOJU Node SDK は、KOMOJU Payments API に対応した TypeScript/JavaScript クライアントです。あらゆる Node.js アプリケーションやフレームワークで利用できます。

ソースコードは GitHub で公開しています。利用可能なエンドポイントやモデルの詳細については、KOMOJU API リファレンスをご参照ください。

はじめに

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

npm install @komoju/komoju-sdk

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

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

const config = new Configuration();
config.setApiKey('YOUR_SECRET_KEY');

例: ホストページ決済

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

1. Session の作成

顧客が支払いの準備ができたら、Session を作成し、返された 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. Return URL の処理

顧客が支払いを完了すると、KOMOJU は session_id クエリパラメータを付加して returnUrl にリダイレクトします。

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

Session を取得して結果を確認します。

const { session_id } = req.query;

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

if (komojuSession.status === SessionStatus.Completed) {
  // payment.status は "captured"、"authorized"、または "pending" になります
  console.log(`Payment ${komojuSession.payment.status}`);
} else {
  console.log('支払いがキャンセルまたは失敗しました');
}

3. Webhook の設定（推奨）

ステップ2のリダイレクトは、顧客がブラウザを閉じたりネットワーク障害が発生した場合に失敗することがあります。また、コンビニ払いのように支払いの確定が後になるケースもあります。これらに対応するため、payment.captured、payment.authorized、payment.cancelled などのイベントを受信する Webhook の設定を推奨します。Webhook URL は KOMOJU マーチャントダッシュボードから設定できます。

エラー処理

API エラーは HTTP ステータスコードとエラーの詳細を含む例外としてスローされます。

try {
  const session = await sessionsApi.showSession({ id: 'sess_xxx' });
} catch (error) {
  console.error(error.response.status);   // 例: 404
  console.error(error.response.data);     // エラーの詳細
}

Issues

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