Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

L’SDK Ruby fornisce un modo semplice e intuitivo per integrare i pagamenti Dodo nelle tue applicazioni Ruby. Segue le convenzioni e le migliori pratiche di Ruby, offrendo una gestione degli errori completa, paginazione e supporto per middleware.

​
Installazione

Aggiungi la gem al tuo Gemfile:
Gemfile
gem "dodopayments", "~> 2.9"
Usa sempre la versione più recente dell’SDK per accedere alle funzionalità più nuove di Dodo Payments. Esegui bundle update dodopayments regolarmente per restare aggiornato.
Poi esegui: 
bundle install
L’SDK supporta Ruby 3.2.0 e versioni successive, con tipi completi, gestione degli errori e meccanismi di retry.

​
Avvio Veloce

Inizializza il client e crea una sessione di checkout: 
require "bundler/setup"
require "dodopayments"

dodo_payments = Dodopayments::Client.new(
  bearer_token: ENV["DODO_PAYMENTS_API_KEY"], # This is the default and can be omitted
  environment: "test_mode" # defaults to "live_mode"
)

checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}]
)

puts(checkout_session_response.session_id)
Conserva le tue chiavi API in modo sicuro usando variabili d’ambiente. Non inserirle mai nel controllo versione né esporle nel codice.

​
Caratteristiche Principali

Ruby Conventions

Segue le convenzioni di nomenclatura e i pattern idiomatici di Ruby

Elegant Syntax

API pulita e leggibile che risulta naturale per gli sviluppatori Ruby

Auto-Pagination

Iteratori per auto-paginazione integrati nelle risposte di elenco

Type Safety

Tipi opzionali Sorbet per una maggiore sicurezza dei tipi

​
Configurazione

​
Configurazione del Timeout

Configura i timeout delle richieste: 
# Configure default for all requests (default is 60 seconds)
dodo_payments = Dodopayments::Client.new(
  timeout: nil # disable timeout
)

# Or, configure per-request
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {timeout: 5}
)

​
Configurazione del Retry

Configura il comportamento di ripetizione automatica: 
# Configure default for all requests (default is 2)
dodo_payments = Dodopayments::Client.new(
  max_retries: 0 # disable retries
)

# Or, configure per-request
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {max_retries: 5}
)

​
Operazioni Comuni

​
Crea una Sessione di Checkout

Genera una sessione di checkout: 
session = dodo_payments.checkout_sessions.create(
  product_cart: [
    {
      product_id: "prod_123",
      quantity: 1
    }
  ],
  return_url: "https://yourdomain.com/return"
)

# Redirect to checkout
redirect_to session.url

​
Gestisci i Clienti

Crea e recupera informazioni sui clienti: 
# Create a customer
customer = dodo_payments.customers.create(
  email: "customer@example.com",
  name: "John Doe",
  metadata: {
    user_id: "12345"
  }
)

# Retrieve customer
customer = dodo_payments.customers.retrieve("cus_123")
puts "Customer: #{customer.name} (#{customer.email})"

​
Gestisci Abbonamenti

Crea e gestisci abbonamenti ricorrenti: 
# Create a subscription
subscription = dodo_payments.subscriptions.create(
  billing: {
    country: "US",
    city: "San Francisco",
    state: "CA",
    street: "1 Market St",
    zipcode: "94105"
  },
  customer: { customer_id: "cus_123" }, # or { email: "...", name: "..." } for a new customer
  product_id: "pdt_456",
  quantity: 1
)

# Charge an on-demand subscription
# product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
charge = dodo_payments.subscriptions.charge(
  subscription.subscription_id,
  product_price: 2500
)

# Update subscription metadata
updated = dodo_payments.subscriptions.update(
  subscription.subscription_id,
  metadata: { plan_type: "premium" }
)
billing richiede almeno il codice country ISO a due lettere. customer accetta sia { customer_id: "..." } per collegare un cliente esistente sia { email: "...", name: "..." } per crearne uno nuovo. product_price è nella denominazione di valuta più bassa.

​
Paginazione

​
Auto-Paginazione

Iterare automaticamente attraverso tutte le pagine: 
page = dodo_payments.payments.list

# Fetch single item from page
payment = page.items[0]
puts(payment.brand_id)

# Automatically fetches more pages as needed
page.auto_paging_each do |payment|
  puts(payment.brand_id)
end

​
Paginazione Manuale

Per avere più controllo sulla paginazione: 
page = dodo_payments.payments.list

if page.next_page?
  new_page = page.next_page
  puts(new_page.items[0].brand_id)
end

​
Gestione degli Errori

Gestire vari errori dell’API Dodo Payments: 
begin
  checkout_session = dodo_payments.checkout_sessions.create(
product_cart: [{product_id: "product_id", quantity: 1}]
  )
rescue Dodopayments::Errors::APIConnectionError => e
  puts("The server could not be reached")
  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
rescue Dodopayments::Errors::RateLimitError => e
  puts("A 429 status code was received; we should back off a bit.")
rescue Dodopayments::Errors::APIStatusError => e
  puts("Another non-200-range status code was received")
  puts(e.status)
end
Implementare la logica di ripetizione con backoff esponenziale per gli errori di limite di velocità per garantire che la tua applicazione gestisca in modo efficace scenari ad alto volume.

​
Sicurezza dei Tipi con Sorbet

Usa Sorbet per parametri di richiesta sicuri per tipo: 
# Type-safe using Sorbet RBI definitions
dodo_payments.checkout_sessions.create(
  product_cart: [
    Dodopayments::ProductItemReq.new(
      product_id: "product_id",
      quantity: 1
    )
  ]
)

# Hashes work, but are not typesafe
dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}]
)

# You can also splat a full Params class
params = Dodopayments::CheckoutSessionCreateParams.new(
  product_cart: [
    Dodopayments::ProductItemReq.new(
      product_id: "product_id",
      quantity: 1
    )
  ]
)
dodo_payments.checkout_sessions.create(**params)

​
Uso Avanzato

​
Endpoint Non Documentati

Effettua richieste a endpoint non documentati: 
response = dodo_payments.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)

​
Parametri Non Documentati

Invia parametri non documentati: 
checkout_session_response = dodo_payments.checkout_sessions.create(
  product_cart: [{product_id: "product_id", quantity: 1}],
  request_options: {
    extra_query: {my_query_parameter: value},
    extra_body: {my_body_parameter: value},
    extra_headers: {"my-header": value}
  }
)

# Access undocumented response properties
puts(checkout_session_response[:my_undocumented_property])

​
Integrazione con Rails

​
Creare un Inizializzatore

Crea config/initializers/dodo_payments.rb: 
require "dodopayments"

DODO_CLIENT = Dodopayments::Client.new(
  bearer_token: Rails.application.credentials.dodo_api_key,
  environment: Rails.env.production? ? "live_mode" : "test_mode"
)

​
Modello del Servizio

Crea un servizio di pagamento: 
# app/services/payment_service.rb
class PaymentService
  def initialize
    @client = DODO_CLIENT
  end

  def create_checkout(items)
    @client.checkout_sessions.create(
      product_cart: items,
      return_url: Rails.application.routes.url_helpers.checkout_return_url
    )
  end

  def process_payment(amount:, currency:, customer_id:)
    @client.payments.create(
      amount: amount,
      currency: currency,
      customer_id: customer_id
    )
  end
end

​
Integrazione con il Controller

Usa nei tuoi controller Rails: 
# app/controllers/checkouts_controller.rb
class CheckoutsController < ApplicationController
  def create
    service = PaymentService.new
    session = service.create_checkout(checkout_params[:items])
    
    redirect_to session.url, allow_other_host: true
  rescue Dodopayments::Errors::APIError => e
    flash[:error] = "Payment error: #{e.message}"
    redirect_to cart_path
  end

  private

  def checkout_params
    params.require(:checkout).permit(items: [:product_id, :quantity])
  end
end

​
Integrazione con Sinatra

Usa con applicazioni Sinatra: 
require "sinatra"
require "dodopayments"

configure do
  set :dodo_client, Dodopayments::Client.new(
    bearer_token: ENV["DODO_API_KEY"]
  )
end

post "/create-checkout" do
  content_type :json
  
  begin
    session = settings.dodo_client.checkout_sessions.create(
      product_cart: JSON.parse(request.body.read)["items"],
      return_url: "#{request.base_url}/return"
    )
    
    { checkout_url: session.url }.to_json
  rescue Dodopayments::Errors::APIError => e
    status 400
    { error: e.message }.to_json
  end
end

​
Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

API Reference

Documentazione completa dell’API

Discord Community

Ottieni aiuto e connettiti con gli sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

​
Supporto

Hai bisogno di aiuto con il Ruby SDK?

​
Contribuzione

Accogliamo con favore i contributi! Consulta le linee guida per i contributi per iniziare.
Last modified on May 14, 2026