komoju-sdk

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

For a full reference of all available endpoints and models, see the KOMOJU API Reference.

Installation

Add to your Gemfile:

gem 'komoju-sdk', '~> 1.0.0'

Then run bundle install.

Quick Start

require 'komoju-sdk'

Komoju.configure do |config|
  config.api_key = 'YOUR_SECRET_KEY'
  # Use a test key during development
end

Get your API keys from the KOMOJU Merchant Settings.

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:

begin
  payment = payments_api.show_payment('pay_xxx')
rescue Komoju::ApiError => e
  puts e.code     # HTTP status code (e.g. 404, 422)
  puts e.message  # Human-readable error description
end

Documentation

Full API reference is auto-generated in the docs/ folder of this gem.

All URIs are relative to https://komoju.com/api/v1

Class Method HTTP request Description
Komoju::BarcodesApi show_barcode GET /barcodes/payment_id Barcode: Show
Komoju::ChargebacksApi accept_chargeback_request POST /chargeback_requests/id/accept Chargeback: Accept
Komoju::ChargebacksApi defend_chargeback_request POST /chargeback_requests/id/defend Chargeback: Defend
Komoju::ChargebacksApi list_chargeback_requests GET /chargeback_requests Chargeback: List
Komoju::ChargebacksApi show_chargeback_request GET /chargeback_requests/id Chargeback: Show
Komoju::DisbursementsApi cancel_disbursement POST /disbursements/id/cancel Disbursement: Cancel
Komoju::DisbursementsApi create_disbursement POST /disbursements Disbursement: Create
Komoju::DisbursementsApi disbursement_report GET /disbursements/report Disbursement: Report
Komoju::DisbursementsApi list_disbursements GET /disbursements Disbursement: List
Komoju::DisbursementsApi show_disbursement GET /disbursements/id Disbursement: Show
Komoju::EventsApi list_events GET /events Event: List
Komoju::EventsApi show_event GET /events/id Event Show
Komoju::OneClickApi delete_external_customer DELETE /external_customers/id External Customer: Destroy
Komoju::PaymentsApi cancel_payment POST /payments/id/cancel Payment: Cancel
Komoju::PaymentsApi capture_payment POST /payments/id/capture Payment: Capture
Komoju::PaymentsApi create_payment POST /payments Payment: Create
Komoju::PaymentsApi create_refund_request POST /payments/id/refund_request Payment: Refund Request
Komoju::PaymentsApi finalize_payment POST /payments/id/finalize Payment: Finalize
Komoju::PaymentsApi list_payment_methods GET /payment_methods Payment Method: List
Komoju::PaymentsApi list_payments GET /payments Payment: List
Komoju::PaymentsApi refund_payment POST /payments/id/refund Payment: Refund
Komoju::PaymentsApi show_payment GET /payments/id Payment: Show
Komoju::PaymentsApi update_payment PATCH /payments/id Payment: Update
Komoju::PlatformModelApi balance_transfer POST /balances/currency/transfer Balance: Transfer
Komoju::PlatformModelApi create_file POST /merchants/merchant_id/files File: Create
Komoju::PlatformModelApi create_merchant POST /merchants Merchant: Create
Komoju::PlatformModelApi create_merchant_balance_transfer POST /merchants/merchant_id/balances/currency/transfer Balance: Transfer
Komoju::PlatformModelApi edit_merchant_balance_settings PUT /merchants/merchant_id/balances/currency/settings Balances: Edit Settings
Komoju::PlatformModelApi list_live_application_payment_methods GET /live_application/merchant_id/payment_methods Live Application: Payment Methods
Komoju::PlatformModelApi list_merchants GET /merchants Merchant: List
Komoju::PlatformModelApi list_submerchant_payments GET /merchants/merchant_id/payments Payment: List for Merchant
Komoju::PlatformModelApi list_submerchant_settlements GET /merchants/merchant_id/settlements Settlement: List
Komoju::PlatformModelApi merchant_balance_transactions GET /merchants/merchant_id/balances/currency/transactions Balance: Transactions
Komoju::PlatformModelApi show_file GET /merchants/merchant_id/files/id File: Show
Komoju::PlatformModelApi show_live_application GET /live_application/merchant_id Live Application: Show
Komoju::PlatformModelApi show_live_application_payment_method GET /live_application/merchant_id/payment_methods/payment_method Live Application: Show Payment Method
Komoju::PlatformModelApi show_merchant GET /merchants/id Merchant: Show
Komoju::PlatformModelApi show_merchant_balance GET /merchants/merchant_id/balances/currency Balance: Show
Komoju::PlatformModelApi show_merchant_balance_settings GET /merchants/merchant_id/balances/currency/settings Balance: Show Settings
Komoju::PlatformModelApi show_merchant_balance_transaction GET /merchants/merchant_id/balances/currency/transactions/transaction_uuid Balance: Transaction
Komoju::PlatformModelApi show_submerchant_settlement GET /merchants/merchant_id/settlements/id Settlement: Show
Komoju::PlatformModelApi simulate_live_application_payment_method_status PATCH /live_application/merchant_id/payment_methods/payment_method/simulate_status Live Application: Simulate Payment Method Status
Komoju::PlatformModelApi simulate_live_application_status PATCH /live_application/merchant_id/simulate_status Live Application: Simulate Status
Komoju::PlatformModelApi submerchant_settlement_csv GET /merchants/merchant_id/settlements/id/csv Settlement: CSV
Komoju::PlatformModelApi submerchant_settlement_pdf GET /merchants/merchant_id/settlements/id/pdf Settlement: PDF
Komoju::PlatformModelApi submerchant_settlement_xls GET /merchants/merchant_id/settlements/id/xls Settlement: XLS
Komoju::PlatformModelApi update_live_application PATCH /live_application/merchant_id Live Application: Update
Komoju::PlatformModelApi update_live_application_payment_method PATCH /live_application/merchant_id/payment_methods/payment_method Live Application: Update Payment Method
Komoju::PlatformModelApi update_merchant PATCH /merchants/id Merchant: Update
Komoju::SecureTokensApi create_secure_token POST /secure_tokens SecureToken: Create
Komoju::SecureTokensApi show_secure_token GET /secure_tokens/id SecureToken: Show
Komoju::SessionsApi cancel_session POST /sessions/id/cancel Session: Cancel
Komoju::SessionsApi create_session POST /sessions Session: Create
Komoju::SessionsApi pay_session POST /sessions/id/pay Session: Pay
Komoju::SessionsApi show_session GET /sessions/id Session: Show
Komoju::SettlementsApi balance_transactions GET /balances/currency/transactions Balance: Transactions
Komoju::SettlementsApi list_settlements GET /settlements Settlement: Index
Komoju::SettlementsApi show_balance GET /balances/currency Balance: Show
Komoju::SettlementsApi show_settlement GET /settlements/id Settlement: Show
Komoju::SettlementsApi show_settlement_csv GET /settlements/id/csv Settlement: CSV
Komoju::SettlementsApi show_settlement_pdf GET /settlements/id/pdf Settlement: PDF
Komoju::SettlementsApi show_settlement_xls GET /settlements/id/xls Settlement: XLS
Komoju::SettlementsApi show_transaction GET /balances/currency/transactions/transaction_uuid Balance: Transaction
Komoju::SubscriptionsApi create_customer POST /customers Customer: Create
Komoju::SubscriptionsApi create_subscription POST /subscriptions Subscription: Create
Komoju::SubscriptionsApi delete_customer DELETE /customers/id Customer: Destroy
Komoju::SubscriptionsApi delete_subscription DELETE /subscriptions/id Subscription: Destroy
Komoju::SubscriptionsApi list_customers GET /customers Customer: List
Komoju::SubscriptionsApi list_subscriptions GET /subscriptions Subscription: List
Komoju::SubscriptionsApi show_customer GET /customers/id Customer: Show
Komoju::SubscriptionsApi show_subscription GET /subscriptions/id Subscription: Show
Komoju::SubscriptionsApi update_customer PATCH /customers/id Customer: Update
Komoju::TokensApi create_token POST /tokens Token: Create

Models

Authorization

Authentication schemes defined for the API:

api_key

  • Type: HTTP basic authentication (API key as username, blank password)

Support