---
title: "Ruby"
description: "KOMOJU Payments APIに対応した公式Ruby SDK（gem）の導入、セッション作成、Webhook署名検証、エラー処理についてのガイドです。"
url: "https://docs.komoju.com/ja/docs/development/sdks/ruby"
source_url: "https://docs.komoju.com/ja/docs/development/sdks/ruby.md"
language: ja
last_modified: "2026-06-26"
---

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

ソースコードは [GitHub](https://github.com/komoju/komoju-ruby-sdk) で公開しています。利用可能なエンドポイントやモデルの詳細については、[KOMOJU API リファレンス](https://docs.komoju.com/en/api-reference)をご参照ください。

# はじめに

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

```ruby
gem 'komoju-sdk'

```

[KOMOJU マーチャント設定](https://komoju.com/merchant/settings)から API キーを取得し、クライアントを設定します。

```ruby
require 'komoju-sdk'

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

```

# 例: ホストページ決済

以下は、基本的なホストページ決済フローのサンプルです。詳細については、[ホストページ実装ガイド](https://docs.komoju.com/ja/docs/integration-guides/hosted-page-standard-mode.md)をご参照ください。

## 1. Session の作成

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

```ruby
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 を取得して結果を確認します。

```ruby
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](https://docs.komoju.com/ja/docs/introduction/webhooks.md) の設定を推奨します。Webhook URL は [KOMOJU マーチャントダッシュボード](https://komoju.com/merchant/settings)から設定できます。

### Webhook 署名の検証

Webhook リクエストが KOMOJU から送信されたものであることを確認するには、Webhook の作成または更新時に **secret token** を設定してください。KOMOJU はすべての配信において、リクエストボディの生データを使った SHA-256 HMAC 署名を `X-Komoju-Signature` ヘッダーに付加します。アプリケーション側で同じ署名を計算して照合することで、リクエストの正当性を検証できます。

詳細とコードサンプルは [Webhook → Secret Token](https://docs.komoju.com/ja/docs/introduction/webhooks.md#secret-token) をご参照ください。

# エラー処理

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

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

```

# Issues

問題が発生した場合やフィードバックがあれば、[GitHub](https://github.com/komoju/komoju-ruby-sdk/issues) よりご連絡ください。