KOMOJU Ruby SDK は、KOMOJU Payments API に対応したフル機能の gem です。Rails を含むあらゆる Ruby アプリケーションやフレームワークで利用できます。

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

はじめに

Gemfile に以下を追加し、bundle install を実行してください。

gem 'komoju-sdk'

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

require 'komoju-sdk'

Komoju.configure do |config|
  config.api_key = 'YOUR_SECRET_KEY'
end

例: ホストページ決済

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

1. Session の作成

顧客が支払いの準備ができたら、Session を作成し、返された session_url にリダイレクトします。

sessions_api = Komoju::SessionsApi.new

session = sessions_api.create_session(
  Komoju::CreateSessionRequestWithPaymentMode.new(
    mode: 'payment',
    amount: 1000,
    currency: 'JPY',
    return_url: 'https://your-site.com/orders/return'
  )
)

redirect_to session.session_url, allow_other_host: true

2. Return URL の処理

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

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

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

sessions_api = Komoju::SessionsApi.new
komoju_session = sessions_api.show_session(params[:session_id])

if komoju_session.status == Komoju::SessionStatus::COMPLETED
  # payment.status は "captured"、"authorized"、または "pending" になります
  puts "Payment #{komoju_session.payment.status}"
else
  puts "支払いがキャンセルまたは失敗しました"
end

3. Webhook の設定（推奨）

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

エラー処理

API エラーはすべて Komoju::ApiError として発生します。HTTP ステータスコードとエラーメッセージを取得できます。

begin
  payment = payments_api.create_payment(...)
rescue Komoju::ApiError => e
  puts "Error #{e.code}: #{e.message}"
end

Issues

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