Skip to main content
View as Markdown

Inttegro Ruby SDK

The Inttegro Ruby SDK builds server-side integrations with Ruby-native resource methods, generated request and domain models, typed API enums, and Sorbet support for teams that want static checks.

Start with MCP

Before writing SDK code, connect your MCP client and ask MCP to design the integration 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. Add the gem with Bundler:

bundle add inttegro
Keep the SDK on the server

Load the secret API key securely from server-side code. Never place the key in browser code, a mobile application, or source control.

Create a client

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 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.

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

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 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 before creating the client. The SDK then uses the application-owned provider:

require "opentelemetry/sdk"
require "inttegro"

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

Inttegro emits vendor-neutral OpenTelemetry spans through the provider configured by your application. The SDK does not choose an exporter or observability vendor, and it does not send telemetry by itself.

Each public SDK call creates one CLIENT span named after the logical operation, such as inttegro.orders.create. HTTP attempts, retries, response receipt, decoding, and failures appear as events on that span. W3C trace context is propagated on outbound requests.

Span attributes and data-safety contract

The stable attributes are:

  • inttegro.operation.name, SDK language and SDK version
  • HTTP method and response status when available
  • destination host and the static API route template
  • the safe request identifier returned by the API
  • a low-cardinality failure category such as a timeout

SDK telemetry never records API keys, authorization headers, request or response bodies, customer or payment data, resource identifiers, dynamic URLs, query strings, exception messages, or stack traces.

To turn off Inttegro instrumentation for a client, use telemetry_enabled: false.

Report SDK failures​

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

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
)

The default policy reports transport, timeout, decoding, SDK, unknown, and server-side failures. Expected API failures such as normal 4xx responses stay with the caller. Use error_reporting_policy: :all when the collector should receive those failures too. Cancellation is never reported.

When the collector needs a JSON-compatible payload, use report.serialize.

Report fields and data-safety contract

A report contains:

  • the logical operation, static route, server host, status, duration, and safe request identifier when available
  • safe API error codes and a stable, low-cardinality fingerprint
  • SDK identity, exception type, and active trace identifiers

Reports never contain API keys, authorization headers, request or response bodies, customer or payment data, resource identifiers, dynamic URLs, query strings, exception messages, or stack traces.

Reporting is completely opt-in. Unless error_reporter is configured, the SDK does no reporting-specific timing or metadata preparation, creates no event ID or report object, and serializes nothing. Report construction and collector failures are isolated, so the caller still receives the original SDK failure.

Continue