---
title: "Ruby SDK"
description: "Official KOMOJU Ruby SDK client library for interacting with the KOMOJU Payments API, including session creation and webhook signature verification."
url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/sdks/ruby"
source_url: "https://docs.priv.staging.komoju-dev.tools/en/docs/development/sdks/ruby.md"
language: en
last_modified: "2026-06-26"
---

The KOMOJU Ruby SDK is a full-featured gem for the KOMOJU Payments API. It works with any Ruby application or framework, including Rails.

The source code is freely available on [GitHub](https://github.com/komoju/komoju-ruby-sdk). For a full reference of all available endpoints and models, see the [KOMOJU API Reference](https://docs.priv.staging.komoju-dev.tools/en/api-reference).

# Getting Started

Add the gem to your `Gemfile` and run `bundle install`.

```ruby
gem 'komoju-sdk'

```

Get your API keys from [KOMOJU Merchant Settings](https://komoju.com/merchant/settings) and configure the client.

```ruby
require 'komoju-sdk'

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

```

# 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](https://docs.priv.staging.komoju-dev.tools/en/docs/integration-guides/hosted-page-standard-mode.md).

## 1. Creating a Session

When your customer is ready to pay, create a session and redirect them to the returned `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. 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:

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

if komoju_session.status == Komoju::SessionStatus::COMPLETED
  # payment.status will be "captured", "authorized", or "pending"
  puts "Payment #{komoju_session.payment.status}"
else
  puts "Payment was cancelled or failed"
end

```

## 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](https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/webhooks.md) to listen for payment events such as `payment.captured`, `payment.authorized`, and `payment.cancelled`. Configure your webhook URL in the [KOMOJU Merchant Dashboard](https://komoju.com/merchant/settings).

### 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](https://docs.priv.staging.komoju-dev.tools/en/docs/introduction/webhooks.md#secret-token) for the full explanation and code examples.

# Error Handling

All API errors raise `Komoju::ApiError`. The exception exposes the HTTP status code and a human-readable message.

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

```

# Issues

If you run into any problems or have feedback, feel free to open an issue on [GitHub](https://github.com/komoju/komoju-ruby-sdk/issues).