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. For a full reference of all available endpoints and models, see the KOMOJU API Reference.

Getting Started

Add the gem to your Gemfile and run bundle install.

gem 'komoju-sdk'

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

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.

1. Creating a Session

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

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 to listen for payment events such as payment.captured, payment.authorized, and payment.cancelled. Configure your webhook URL in the KOMOJU Merchant Dashboard.

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 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.

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.