yookassa/README.md

YooKassa API Ruby Client

Installation

Add this line to your application's Gemfile:

gem 'yookassa'

And then execute:

$ bundle

Or install it yourself as:

$ gem install yookassa

Usage

Configuration

First of all you need to setup credentials to use Yookassa. You can configure your instance of Yookassa once in a application booting time. Ex. if you use rails, just put these lines into initializer file

# config/initializers/yookassa.rb

Yookassa.configure do |config|
  config.shop_id = ENV.fetch('YOOKASSA_SHOP_ID') # or put your shop_id and api_key here directly
  config.api_key = ENV.fetch('YOOKASSA_API_KEY') # can be taken from Rails.credentials too
end

There are some cases, when you need to connect to different Yookassa accounts (say, your clients need to connect to Yookassa). That probably means that you run a marketplace or multitenant system. There is a solution for this one from Yookassa, see https://yookassa.ru/en/developers/special-solutions/checkout-for-platforms/basics or https://yookassa.ru/en/developers/partners-api/basics

If that is not your case, and you still have multiple shop_ids and api_keys, and need to handle all of them under one application, then you need to instantiate clients inline

client1 = Yookassa::Payments.new(shop_id: 'shop_1', api_key: '123')
client2 = Yookassa::Payments.new(shop_id: 'shop_2', api_key: '456')

Making Payments

Creating payment

payload = {
    amount: {
        value:    100,
        currency: 'RUB'
    },
    capture:      true,
    confirmation: {
        type:       'redirect',
        return_url: return_url
    }
}

payment = Yookassa.payments.create(payment: payload)

# or

payments = Yookassa::Payments.new(shop_id: 'shop_1', api_key: '123')
payment = payments.create(payment: payload)

Other payment requests

Yookassa.payments.find(payment_id: '12345')
Yookassa.payments.capture(payment_id: '12345')
Yookassa.payments.cancel(payment_id: '12345')

Rails webhook endpoint (engine)

The gem ships with a Rails engine and a default webhook controller you can use directly.

1. Configure the webhook token and (optionally) allowed source IPs:

# config/initializers/yookassa.rb
Yookassa.configure do |config|
  config.shop_id = ENV.fetch('YOOKASSA_SHOP_ID')
  config.api_key = ENV.fetch('YOOKASSA_API_KEY')

  # Random, long, secret token used in webhook URL path.
  config.webhook_token = ENV.fetch('YOOKASSA_WEBHOOK_TOKEN')

  # Optional override. Defaults come from YooKassa docs:
  # https://yookassa.ru/developers/using-api/webhooks#ip
  # config.webhook_allowed_ips = ['185.71.76.0/27', ...]
end

2. Mount the engine in routes:

# config/routes.rb
Rails.application.routes.draw do
  mount Yookassa::Engine => '/yookassa'
end

This exposes:

• POST /yookassa/webhooks/:token

Set your YooKassa webhook URL to include the real token value, for example:

• https://example.com/yookassa/webhooks/<long-random-token>

The default Yookassa::WebhooksController verifies:

• token in URL path
• request source request.remote_ip is in allowlist
• webhook object matches fresh API fetch by id and status

No signature headers are used.

Overriding webhook handling

In host app, inherit from the gem controller and implement business logic in process_webhook:

# app/controllers/my_yookassa_webhooks_controller.rb
class MyYookassaWebhooksController < Yookassa::WebhooksController
  private

  def process_webhook(payload)
    object = payload['object'] || payload.dig('data', 'object')
    return unless object

    # Your app-specific processing
  end
end

Then route to your controller (keeping token in path):

# config/routes.rb
post '/webhooks/yookassa/:token', to: 'my_yookassa_webhooks#create'

Path to 1.0

Настройки SDK API ЮKassa

• Аутентификация
• Статистические данные об используемом окружении
• Получение информации о магазине
• Работа с Webhook
• Входящие уведомления

Работа с платежами

• Запрос на создание платежа
• Запрос на создание платежа через билдер
• Запрос на частичное подтверждение платежа
• Запрос на отмену незавершенного платежа
• Получить информацию о платеже
• Получить список платежей с фильтрацией
• Контракт на добавление платежа
• Запись реальных валидных и невалидных запросов и ответов

Работа с возвратами

• Запрос на создание возврата
• Запрос на создание возврата через билдер
• Получить информацию о возврате
• Получить список возвратов с фильтрацией
• Контракт на добавление возврата
• Запись реальных валидных и невалидных запросов и ответов

Работа с чеками

• Запрос на создание чека
• Запрос на создание чека через билдер
• Получить информацию о чеке
• Получить список чеков с фильтрацией
• Контракт на добавление возврата
• Запись реальных валидных и невалидных запросов и ответов

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

Development

This gem uses rs-httpclient to avoid the http gem's llhttp-ffi dependency chain.

bin/setup
bundle exec rspec
bundle exec rubocop

License

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