Ruby SDK

The Ruby SDK includes built-in support for Rails applications and comes with comprehensive documentation and examples. It's designed to make implementing payments in your Ruby applications straightforward and secure.

Installation

Add the gem to your Gemfile:

gem 'cari-finance'

Then run:

bundle install

Or install it directly:

gem install cari-finance

Basic usage

To start using the SDK, initialize it with your API key:

require 'cari_finance'

# Initialize with your API key
cari_finance = CariFinance::Client.new(api_key: 'sk_test_51NzaWTBOIWoX8E7wnMd1...')

# The SDK will automatically detect if you're using a test or live key

Creating charges

You can create a new charge for a single payment:

# Create a charge
charge = cari_finance.charges.create(
  amount: 2000, # Amount in cents (e.g., $20.00)
  currency: 'usd',
  provider: 'card',
  card: {
    token: 'tok_visa' # Token obtained from the client-side SDK
  },
  description: 'Payment for order #123',
  customer: {
    name: 'John Doe',
    email: 'john.doe@example.com'
  }
)

# Check if charge was successful
if charge.status == 'succeeded'
  # Payment was successful
  puts "Payment successful! Charge ID: #{charge.id}"
else
  # Payment failed
  puts "Payment failed: #{charge.failure_message}"
end

Working with customers

You can create and manage customers:

# Create a new customer
customer = cari_finance.customers.create(
  name: 'Jane Smith',
  email: 'jane.smith@example.com',
  phone: '+18765551234',
  address: {
    line1: '123 Main St',
    city: 'Roseau',
    country: 'DM'
  }
)

# Retrieve a customer
customer = cari_finance.customers.retrieve('cus_12345')

# Update a customer
customer = cari_finance.customers.update('cus_12345', {
  phone: '+18765559876'
})

# Delete a customer
cari_finance.customers.delete('cus_12345')

Rails integration

For Rails applications, create an initializer at config/initializers/cari_finance.rb:

CariFinance.configure do |config|
  config.api_key = ENV['CARI_FINANCE_API_KEY']

  # Optional configuration
  config.api_version = '2023-10-01'
  config.timeout = 30 # in seconds
end

Add the following to your Gemfile:

gem 'cari-finance'
gem 'dotenv-rails', groups: [:development, :test]

Create a .env file in your project root:

CARI_FINANCE_API_KEY=sk_test_51NzaWTBOIWoX8E7wnMd1...

Then in your controllers:

class PaymentsController < ApplicationController
  def create
    @charge = CariFinance::Charge.create(
      amount: params[:amount],
      currency: 'usd',
      provider: 'card',
      card: { token: params[:token] },
      description: "Payment for order #{params[:order_id]}"
    )

    if @charge.status == 'succeeded'
      # Handle successful payment
      redirect_to order_path(params[:order_id]), notice: 'Payment successful!'
    else
      # Handle failed payment
      flash[:alert] = "Payment failed: #{@charge.failure_message}"
      render :new
    end
  end
end

Error handling

The SDK uses exceptions to handle errors:

begin
  charge = cari_finance.charges.create(
    amount: 2000,
    currency: 'usd',
    # other parameters...
  )
rescue CariFinance::CardError => e
  # Card was declined
  puts "Card error: #{e.message}"
rescue CariFinance::InvalidRequestError => e
  # Invalid parameters were supplied
  puts "Invalid request: #{e.message}"
rescue CariFinance::AuthenticationError => e
  # Authentication failed
  puts "Authentication error: #{e.message}"
rescue CariFinance::APIError => e
  # Generic API error
  puts "API error: #{e.message}"
end

Additional resources

For more detailed information about the Ruby SDK, refer to these resources: