---
title: "Ruby SDK"
description: "Install, use, and observe the official Inttegro SDK for Ruby."
canonical: "https://studio.inttegro.com/sdks/ruby"
format: inttegro-machine-docs/v1
language: "C#"
sdk_version: "v10.3.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/csharp/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 565
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "general"
recommended_mcp_tools: ["get_integration_guide","check_integration_readiness"]
estimated_tokens: 1881
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Install, use, and observe the official Inttegro SDK for Ruby. This C# representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. When should the reader use Ruby SDK?

Use this SDK guide when the selected runtime or framework matches the application being built.

#### Q2. What is authoritative on this page?

Use this page for orientation; follow its canonical SDK, guide, API, or MCP links for exact contracts.

#### Q3. What page-specific constraint matters most?

Use the current documented SDK version and native public API; do not invent members from JSON names or another language.

#### Q4. Can Inttegro MCP materially help with this task?

Yes, when the reader has an authenticated MCP connection and the task needs live context, guided planning, or a supported operation. The strongest matches are `get_integration_guide`, `check_integration_readiness`; their exact roles and boundaries are listed below.

#### Q5. How should the reader verify the answer and continue?

Install the documented version, compile or type-check the smallest example, run it against a disposable application, and verify the resulting resource through its canonical lookup. Continue with [Choose an API resource](https://studio.inttegro.com/machine/csharp/api.md) and [Rails storefront demo](https://studio.inttegro.com/machine/csharp/demos/rails.md) when those concerns enter scope.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_integration_guide`](https://studio.inttegro.com/machine/csharp/inttegro-mcp/tools.md#get_integration_guide) — read-only integration guidance. Returns a focused implementation sequence and canonical Studio links for authentication, checkout, orders, catalog, messaging, idempotency, or testing.
- [`check_integration_readiness`](https://studio.inttegro.com/machine/csharp/inttegro-mcp/tools.md#check_integration_readiness) — read-only integration guidance. Audits platform secret storage, server-runtime compatibility, idempotency, errors, state verification, checkout returns, and messaging consent without receiving source code or credentials.

## Document content

# Inttegro Ruby SDK

The [Inttegro Ruby SDK](https://rubygems.org/gems/inttegro) builds server-side
integrations with Ruby-native resource methods, generated request and domain
models, typed API enums, and [Sorbet](https://sorbet.org/docs/overview) support
for teams that want static checks.

:::tip Start with MCP

Before writing SDK code, [connect your MCP client](https://studio.inttegro.com/machine/csharp/inttegro-mcp/connect.md) and ask
MCP to [design the integration](https://studio.inttegro.com/machine/csharp/inttegro-mcp/design-integration.md) for
your Ruby application. Use the resulting implementation and test plan to guide
the code you write with this SDK.

:::

## Install

The SDK requires [Ruby 3.0 or newer](https://www.ruby-lang.org/en/downloads/).
Add the gem with [Bundler](https://bundler.io/man/bundle-add.1.html):

```bash
bundle add inttegro
```

:::warning Keep the SDK on the server

[Load the secret API key securely](https://studio.inttegro.com/machine/csharp/api/authentication.md#store-credentials-safely)
from server-side code. Never place the key in browser code, a mobile
application, or source control.

:::

## Create a client

```ruby
require "inttegro"

inttegro = Inttegro::Client.new(
  api_key: ENV.fetch("INTTEGRO_API_KEY")
)
```

## Static typing, when you want it

The SDK is checked with Sorbet and ships its public
[RBI definitions](https://sorbet.org/docs/rbi) with the gem. In a
Sorbet-enabled application, that gives the type checker and editor precise
information about resource methods, returned objects, and API enums. You get
useful completion and earlier feedback without maintaining SDK definitions
yourself.

Sorbet is not required to use Inttegro. Resource methods continue to accept
concise Ruby hashes, so an existing application can integrate without changing
its approach to typing. When stronger checks would help, use the generated
`T::Struct` request classes under a singular resource namespace such as
`Inttegro::Order::CreateRequest`; both styles call the same resource methods and
return the same domain objects.

## Navigate typed resources

Each primary resource is the matching Ruby class. Related models and enums live
beneath that class, keeping the public namespace and autocomplete focused:

```ruby
product = Inttegro::Product.from_hash(product_data)

if product.type == Inttegro::Product::Type::DIGITAL && product.published?
  # Offer the product for sale.
end

payment = Inttegro::Payment.from_hash(payment_data)

if payment.status == Inttegro::Payment::Status::REQUIRES_ACTION
  next_action = payment.required_action
end
```

Question methods such as `paid?`, `requires_action?`, `terminal?`,
`published?`, and `reusable?` inspect the current object only. They never make
an API request.

## See it in a complete app

The [Rails storefront demo](https://studio.inttegro.com/machine/csharp/demos/rails.md) follows a customer from choosing a
product through a hosted checkout, including honest completion and cancellation
states. Follow the guide to see how the Ruby SDK connects the storefront to a
server-owned order and payment flow.

## Observability

Configure [OpenTelemetry](https://opentelemetry.io/docs/languages/ruby/) before
creating the client. The SDK then uses the application-owned provider:

```ruby
require "opentelemetry/sdk"
require "inttegro"

OpenTelemetry::SDK.configure
inttegro = Inttegro::Client.new(
  api_key: ENV.fetch("INTTEGRO_API_KEY")
)
```

> Server Sdk Observability is interactive content. Use the canonical page to view it.

### Report SDK failures

Pass an application-owned callback to receive one immutable, typed report after
an SDK operation finally fails:

```ruby
require "inttegro"

enqueue_error = lambda do |report|
  payload = report.serialize
  _ = payload # Forward the payload to your collector or queue.
end

inttegro = Inttegro::Client.new(
  api_key: ENV.fetch("INTTEGRO_API_KEY"),
  error_reporter: enqueue_error
)
```

> Server Sdk Error Reporting is interactive content. Use the canonical page to view it.

## Continue

- [Browse the generated API reference](https://ruby.inttegro.dev/v10.0.0/)
- [View the gem on RubyGems](https://rubygems.org/gems/inttegro)
- [Browse the source and releases](https://github.com/inttegro/inttegro-sdk-ruby)
- [Run the Rails storefront](https://studio.inttegro.com/machine/csharp/demos/rails.md)
- [Choose an API resource](https://studio.inttegro.com/machine/csharp/api.md)