komoju-sdk

Ruby gem for the KOMOJU API — Full featured access to the KOMOJU payments system.

Installation

Add to your Gemfile:

gem 'komoju-sdk', '~> 1.0.0.beta.1'

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.

Accept a Payment

Charge a customer directly with their payment details:

payments_api = Komoju::PaymentsApi.new

begin
  payment = payments_api.create_payment(
    Komoju::CreatePaymentRequestWithPaymentDetails.new(
      amount: 1000,
      currency: 'JPY',
      payment_details: {
        type: 'credit_card',
        number: '4111111111111111',
        month: 12,
        year: 2025,
        verification_value: '123'
      }
    )
  )
  puts "Payment created: #{payment.id} (#{payment.status})"

  # Capture an authorized payment
  captured = payments_api.capture_payment(payment.id, Komoju::CapturePaymentRequest.new)
  puts "Payment captured: #{captured.captured_at}"
rescue Komoju::ApiError => e
  puts "Error #{e.code}: #{e.message}"
end

Hosted Payment Page (Sessions)

Redirect customers to a KOMOJU-hosted checkout page:

sessions_api = Komoju::SessionsApi.new

begin
  session = sessions_api.create_session(
    Komoju::CreateSessionRequestWithPaymentMode.new(
      mode: 'payment',
      amount: 5000,
      currency: 'JPY',
      return_url: 'https://example.com/thank-you',
      default_locale: 'ja'
    )
  )
  puts "Redirect customer to: #{session.session_url}"
rescue Komoju::ApiError => e
  puts "Error #{e.code}: #{e.message}"
end

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::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 PATCH /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 list_settlements GET /settlements Settlement: Index
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