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

# Ruby

> Intégrez Dodo Payments dans vos applications Ruby avec un SDK élégant et natif à Ruby

Le SDK Ruby fournit un moyen simple et intuitif d'intégrer Dodo Payments dans vos applications Ruby. Il suit les conventions et les meilleures pratiques de Ruby, offrant une gestion complète des erreurs, de la pagination et un support middleware.

## Installation

Ajoutez la gem à votre Gemfile :

```ruby Gemfile theme={null}
gem "dodopayments", "~> 2.9"
```

<Tip>
  Utilisez toujours la dernière version du SDK pour accéder aux fonctionnalités les plus récentes de Dodo Payments. Exécutez `bundle update dodopayments` régulièrement pour rester à jour.
</Tip>

Puis exécutez :

```bash theme={null}
bundle install
```

<Info>
  Le SDK prend en charge Ruby 3.2.0 et les versions ultérieures, avec des types complets, la gestion des erreurs et des mécanismes de nouvelle tentative.
</Info>

## Démarrage rapide

Initialisez le client et créez une session de paiement :

```ruby theme={null}
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)
```

<Warning>
  Stockez vos clés API de manière sécurisée en utilisant des variables d’environnement. Ne les validez jamais dans le contrôle de version ni ne les exposez dans votre code.
</Warning>

## Fonctionnalités principales

<CardGroup cols={2}>
  <Card title="Ruby Conventions" icon="gem">
    Suit les conventions de nommage Ruby et les modèles idiomatiques
  </Card>

  <Card title="Elegant Syntax" icon="code">
    API propre et lisible qui semble naturelle pour les développeurs Ruby
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    Itérateurs d’auto-paging intégrés pour les réponses de liste
  </Card>

  <Card title="Type Safety" icon="shield-check">
    Types Sorbet optionnels pour une sécurité de type renforcée
  </Card>
</CardGroup>

## Configuration

### Configuration du délai d'attente

Configurez les délais d'attente des requêtes :

```ruby theme={null}
# 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}
)
```

### Configuration des réessais

Configurez le comportement de réessai automatique :

```ruby theme={null}
# 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}
)
```

## Opérations courantes

### Créer une session de paiement

Générez une session de paiement :

```ruby theme={null}
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.checkout_url
```

### Gérer les clients

Créez et récupérez des informations sur les clients :

```ruby theme={null}
# 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})"
```

### Gérer les abonnements

Créez et gérez des abonnements récurrents :

```ruby theme={null}
# 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" }
)
```

<Info>
  `billing` nécessite au minimum le code ISO à deux lettres `country`. `customer` accepte soit `{ customer_id: "..." }` pour attacher un client existant, soit `{ email: "...", name: "..." }` pour en créer un nouveau. `product_price` est dans la plus petite dénomination de la devise.
</Info>

## Pagination

### Pagination Automatique

Itérer automatiquement à travers toutes les pages :

```ruby theme={null}
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
```

### Pagination Manuelle

Pour un meilleur contrôle de la pagination :

```ruby theme={null}
page = dodo_payments.payments.list

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

## Gestion des Erreurs

Gérer diverses erreurs de l'API Dodo Payments :

```ruby theme={null}
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
```

<Tip>
  Implémentez une logique de reprise avec backoff exponentiel pour les erreurs de limite de débit afin de vous assurer que votre application gère correctement les scénarios à fort volume.
</Tip>

## Sécurité de Type avec Sorbet

Utiliser Sorbet pour des paramètres de requête de type sécurisé :

```ruby theme={null}
# 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)
```

## Utilisation Avancée

### Points de Terminaison Non Documentés

Faire des requêtes vers des points de terminaison non documentés :

```ruby theme={null}
response = dodo_payments.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)
```

### Paramètres Non Documentés

Envoyer des paramètres non documentés :

```ruby theme={null}
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])
```

## Intégration Rails

### Créer un Initialisateur

Créer `config/initializers/dodo_payments.rb` :

```ruby theme={null}
require "dodopayments"

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

### Modèle de l'Objet de Service

Créer un service de paiement :

```ruby theme={null}
# 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
```

### Intégration du Contrôleur

Utiliser dans vos contrôleurs Rails :

```ruby theme={null}
# app/controllers/checkouts_controller.rb
class CheckoutsController < ApplicationController
  def create
    service = PaymentService.new
    session = service.create_checkout(checkout_params[:items])
    
    redirect_to session.checkout_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
```

## Intégration Sinatra

Utiliser avec les applications Sinatra :

```ruby theme={null}
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.checkout_url }.to_json
  rescue Dodopayments::Errors::APIError => e
    status 400
    { error: e.message }.to_json
  end
end
```

## Ressources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-ruby">
    Voir le code source et contribuer
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Documentation complète de l'API
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Obtenir de l'aide et se connecter avec les développeurs
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-ruby/issues">
    Signaler des bugs ou demander des fonctionnalités
  </Card>
</CardGroup>

## Support

Besoin d'aide avec le SDK Ruby ?

* **Discord** : Rejoignez notre [serveur communautaire](https://discord.gg/bYqAp4ayYh) pour un support en temps réel
* **Email** : Contactez-nous à [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub** : Ouvrez un problème sur le [référentiel](https://github.com/dodopayments/dodopayments-ruby)

## Contribuer

Nous accueillons les contributions ! Consultez les [lignes directrices de contribution](https://github.com/dodopayments/dodopayments-ruby/blob/main/CONTRIBUTING.md) pour commencer.