kody-clientsdk-ruby

Kody API - Ruby SDK

This guide provides an overview of using the Kody API and its reference documentation for Ruby.

• Installation
• Authentication
• Quick Start
• Sample code

Installation

Add this line to your application's Gemfile:

gem 'kody-clientsdk-ruby'

And then execute:

bundle install

Or install it yourself as:

gem install kody-clientsdk-ruby

Requirements

• Ruby 2.6.10 or higher
• gRPC support

Authentication

The client library uses a combination of a Store ID and an API key. These will be shared with you during the technical integration onboarding or by your Kody contact.

During development, you will have access to a test Store and test API key, and when the integration is ready for live access, the production credentials will be shared securely with you and associated with a live store that was onboarded on Kody.

The test and live API calls are always compatible, only changing credentials and the service hostname is required to enable the integration in production.

Host names

• Development and test: grpc-staging.kodypay.com
• Live: grpc.kodypay.com

Quick Start

require 'kody'

# Configure the Kody client
Kody.configure do |config|
  config.api_key = 'your-api-key'
  config.store_id = 'your-store-id'
  config.staging! # Use staging environment for testing
end

# Create a client instance
client = Kody::Client.new

# Initiate a payment
begin
  response = client.ecom.initiate_payment(
    payment_reference: Kody::EcomClient.generate_payment_reference,
    amount_minor_units: 2000, # £20.00 in pence
    currency: 'GBP',
    order_id: Kody::EcomClient.generate_order_id,
    return_url: 'https://your-website.com/payment-return'
  )

  puts "Payment initiated successfully!"
  puts "Payment ID: #{response.response.payment_id}"
  puts "Payment URL: #{response.response.payment_url}"

rescue Kody::Error => e
  puts "Error: #{e.message}"
rescue GRPC::BadStatus => e
  puts "gRPC Error: #{e.message}"
end

Configuration Options

Environment Configuration

# Production environment (default)
Kody.configure do |config|
  config.api_key = 'your-production-api-key'
  config.store_id = 'your-production-store-id'
  # config.host defaults to 'grpc.kodypay.com'
end

# Staging environment
Kody.configure do |config|
  config.api_key = 'your-test-api-key'
  config.store_id = 'your-test-store-id'
  config.staging! # Sets host to 'grpc-staging.kodypay.com'
end

# Local development
Kody.configure do |config|
  config.api_key = 'your-api-key'
  config.store_id = 'your-store-id'
  config.development! # Sets host to 'localhost:8080' with TLS disabled
end

Environment Variables

You can also configure using environment variables:

export KODY_API_KEY="your-api-key"
export KODY_STORE_ID="your-store-id"

Kody.configure do |config|
  config.api_key = ENV['KODY_API_KEY']
  config.store_id = ENV['KODY_STORE_ID']
  config.staging! # or production/development
end

Available Methods

E-commerce Payments

Initiate Payment

response = client.ecom.initiate_payment(
  payment_reference: 'unique-payment-ref',
  amount_minor_units: 2000, # Amount in minor units (e.g., pence for GBP)
  currency: 'GBP',
  order_id: 'order-123',
  return_url: 'https://your-site.com/payment-return',
  # Optional parameters:
  order_metadata: '{"item": "Product Name"}',
  expiry: {
    show_timer: true,
    expiring_seconds: 1800 # 30 minutes
  },
  locale: 'en_GB',
  show_order_summary: true,
  show_merchant_name: true
)

Get Payments

response = client.ecom.get_payments(
  page: 1,
  page_size: 10,
  # Optional filter:
  filter: {
    order_id: 'specific-order-id'  # Optional: filter by order ID
  }
)

puts "Total payments: #{response.response.total}"
response.response.payments.each do |payment|
  puts "Payment ID: #{payment.payment_id}"
  puts "Status: #{payment.status}"
  puts "Amount: #{payment.sale_data.amount_minor_units}" if payment.has_sale_data?
end

Note: Currently, initiate_payment and get_payments methods are implemented. Additional methods (payment details, refunds, etc.) will be added in future versions.

Helper Methods

The SDK provides convenient helper methods:

# Generate unique payment reference
payment_ref = Kody::EcomClient.generate_payment_reference
# Returns: "pay_a1b2c3d4e5f6g7h8"

# Generate unique order ID
order_id = Kody::EcomClient.generate_order_id  
# Returns: "order_a1b2c3d4e5f6g7h8"

Sample code

Complete examples can be found in the samples/ directory:

• Initiate Payment
• Get Payments

Documentation

For complete API documentation, examples, and integration guides, please visit: 📚 https://api-docs.kody.com

Development Status

This is a minimal initial version of the Ruby SDK focusing on the core payment initiation functionality. The SDK follows the same patterns as other Kody client SDKs and will be extended with additional features in future releases.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/KodyPay/kody-clientsdk-ruby.

License

The gem is available as open source under the terms of the MIT License.