Saltar al contenido principal

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.

El SDK de Ruby proporciona una forma simple e intuitiva de integrar Dodo Payments en tus aplicaciones Ruby. Sigue las convenciones y mejores prácticas de Ruby, ofreciendo un manejo de errores completo, paginación y soporte para middleware.

​
Instalación

Agrega la gema a tu Gemfile:
Gemfile
gem "dodopayments", "~> 2.9"
Utiliza siempre la versión más reciente del SDK para acceder a las funciones más nuevas de Dodo Payments. Ejecuta bundle update dodopayments regularmente para mantenerte actualizado.
Luego ejecuta: 
bundle install
El SDK es compatible con Ruby 3.2.0 y versiones posteriores, con tipos completos, manejo de errores y mecanismos de reintento.

​
Inicio Rápido

Inicializa el cliente y crea una sesión de pago: 
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)
Almacena tus claves de API de forma segura utilizando variables de entorno. Nunca las agregues al control de versiones ni las expongas en tu código.

​
Características Principales

Ruby Conventions

Sigue las convenciones de nombres de Ruby y los patrones idiomáticos

Elegant Syntax

API limpia y legible que resulta natural para los desarrolladores de Ruby

Auto-Pagination

Iteradores de paginación automática integrados para respuestas de listas

Type Safety

Tipos opcionales de Sorbet para una mayor seguridad de tipos

​
Configuración

​
Configuración de Tiempo de Espera

Configura los tiempos de espera de las solicitudes: 
# 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}
)

​
Configuración de Reintentos

Configura el comportamiento de reintento automático: 
# 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}
)

​
Operaciones Comunes

​
Crear una Sesión de Pago

Genera una sesión de pago: 
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

​
Gestionar Clientes

Crea y recupera información de clientes: 
# 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})"

​
Manejar Suscripciones

Crea y gestiona suscripciones recurrentes: 
# 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 requiere al menos el código ISO de dos letras country. customer acepta ya sea { customer_id: "..." } para adjuntar un cliente existente o { email: "...", name: "..." } para crear uno nuevo. product_price está en la denominación más baja de la moneda.

​
Paginación

​
Auto-Paginación

Iterar automáticamente a través de todas las páginas: 
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

​
Paginación Manual

Para más control sobre la paginación: 
page = dodo_payments.payments.list

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

​
Manejo de Errores

Manejar varios errores de la API de 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
Implementar lógica de reintentos con backoff exponencial para errores de límite de tasa para asegurar que su aplicación maneje escenarios de alto volumen de manera elegante.

​
Seguridad de Tipos con Sorbet

Usar Sorbet para parámetros de solicitud seguros respecto a tipos: 
# 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 Avanzado

​
Endpoints No Documentados

Realizar solicitudes a endpoints no documentados: 
response = dodo_payments.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)

​
Parámetros No Documentados

Enviar parámetros no documentados: 
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])

​
Integración con Rails

​
Crear un Inicializador

Crear 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"
)

​
Patrón de Objeto de Servicio

Crear un servicio de pago: 
# 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

​
Integración de Controlador

Usar en tus controladores de 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

​
Integración con Sinatra

Usar con aplicaciones de 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

​
Recursos

GitHub Repository

Ver código fuente y contribuir

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conecta con desarrolladores

Report Issues

Reportar errores o solicitar funciones

​
Soporte

¿Necesitas ayuda con el SDK de Ruby?

​
Contribuir

¡Damos la bienvenida a las contribuciones! Consulta las directrices para contribuir para comenzar.
Last modified on May 14, 2026