Vindi Rails SDK

Leia em Português (README.pt-BR.md)

Ruby/Rails integration SDK for the Vindi API v1 (recurring billing platform).

Add this line to your application's Gemfile:

gem 'vindi-rails'

And then execute:

$ bundle install

Configure the SDK. In a Rails application, you can run the installation generator to create the initializer template:

$ rails generate vindi:install

This will create config/initializers/vindi.rb where you can set your keys:

Vindi.configure do |config|
  config.api_key = 'your_private_api_key'
  # Optional: Define base URL (default is Sandbox)
  # config.api_url = 'https://gp.vindi.com.br/api/v1'

  # Optional: Configure cache store (e.g. ActiveSupport::Cache::MemoryStore.new or Rails.cache)
  # config.cache_store = Rails.cache
  # config.cache_ttl = 300 # Expiration time in seconds (default is 300)
  # config.cached_resources = [:plans, :products, :discounts, :payment_methods] # Resources to cache

  # Optional: Configure rate limit retries and exponential backoff
  # config.max_retries = 3 # Max retries for rate limits or timeouts (default is 3)
  # config.retry_backoff_factor = 2 # Multiplier for delays (default is 2)
  # config.retry_base_delay = 1.0 # Initial wait time in seconds (default is 1.0)
end

If your application needs to handle multiple Vindi accounts or switch API credentials dynamically (e.g., in a multi-tenant SaaS application), you can use Vindi.with_config to run a block with temporary credentials. This operation is thread-safe:

# Switch key and API url dynamically within a block
Vindi.with_config(api_key: 'another_merchant_api_key', api_url: 'https://gp.vindi.com.br/api/v1') do
  # Any API call here will use the overridden configuration
  customers = Vindi::Customer.list
end

# The original global configuration is automatically restored outside the block

Resources are mapped directly under the Vindi namespace.

# List customers
customers = Vindi::Customer.list(page: 1, per_page: 20)

# Create a customer
customer = Vindi::Customer.create(
  name: 'John Doe',
  email: 'john.doe@example.com',
  registry_code: '12345678909' # CPF/CNPJ
)

# Create a customer with an idempotency key (prevents duplicates)
customer = Vindi::Customer.create(
  { name: 'John Doe', email: 'john.doe@example.com' },
  idempotency_key: 'unique-uuid-or-key'
)

# Update a customer
Vindi::Customer.update(customer.id, name: 'John Doe Updated')

# Delete a customer
Vindi::Customer.delete(customer.id)

To keep the SDK lightweight and free of framework dependencies, Rails-specific features are organized into extensible companion gems:

Handles webhook processing, background jobs, and ActiveRecord synchronization:

• rails generate vindi:webhook: Creates a webhooks controller and background queue job stub to process payment/subscription events safely with built-in security filters and idempotency checks.
• rails generate vindi:webhook_handler [EventName]: Generates a modular event-specific service handler class (e.g. for subscription_canceled), which is automatically dispatched by the main WebhookJob.
• rails generate vindi:sync [Model]: Adds vindi_customer_id and database migrations to synchronize your models (e.g. User) automatically with Vindi via ActiveRecord callbacks.
• rails generate vindi:outbox: Generates a database migration for the transactional outbox table to enable resilient, asynchronous synchronization of ActiveRecord models (avoiding inline external API requests).
• rails vindi:status: A diagnostics Rake task to safely check configured Vindi API credentials, active environments, and verify connectivity.

A mountable Rails Engine carrying pre-built Views, HTML templates, and card tokenization scripts:

• rails generate vindi:checkout: Copies ready-to-use checkout UI templates and Stimulus JS components using Vindi's public keys encryption.

For detailed integration guides, please refer to WIKI.md.

To run the Minitest suite:

bundle exec rake test

For a full list of mapped resources and detailed usage instructions, check out the WIKI.md.