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

> Integrasikan Dodo Payments ke dalam aplikasi Ruby Anda dengan SDK yang elegan dan asli Ruby

SDK Ruby menyediakan cara yang sederhana dan intuitif untuk mengintegrasikan Dodo Payments ke dalam aplikasi Ruby Anda. Ini mengikuti konvensi dan praktik terbaik Ruby, menawarkan penanganan kesalahan yang komprehensif, paginasi, dan dukungan middleware.

## Instalasi

Tambahkan gem ke dalam Gemfile Anda:

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

<Tip>
  Selalu gunakan versi SDK terbaru untuk mengakses fitur Dodo Payments yang paling mutakhir. Jalankan `bundle update dodopayments` secara berkala untuk tetap terbaru.
</Tip>

Kemudian jalankan:

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

<Info>
  SDK mendukung Ruby 3.2.0 dan versi yang lebih baru, dengan tipe lengkap, penanganan kesalahan, dan mekanisme retry.
</Info>

## Memulai dengan Cepat

Inisialisasi klien dan buat sesi checkout:

```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>
  Simpan kunci API Anda dengan aman menggunakan variabel lingkungan. Jangan pernah meng-commit atau mengeksposnya di kode Anda.
</Warning>

## Fitur Utama

<CardGroup cols={2}>
  <Card title="Ruby Conventions" icon="gem">
    Mengikuti konvensi penamaan Ruby dan pola idiomatis
  </Card>

  <Card title="Elegant Syntax" icon="code">
    API yang bersih dan mudah dibaca, terasa alami untuk pengembang Ruby
  </Card>

  <Card title="Auto-Pagination" icon="arrows-rotate">
    Iterator auto-paging bawaan untuk respons daftar
  </Card>

  <Card title="Type Safety" icon="shield-check">
    Tipe Sorbet opsional untuk keamanan tipe yang lebih baik
  </Card>
</CardGroup>

## Konfigurasi

### Konfigurasi Timeout

Konfigurasi timeout permintaan:

```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}
)
```

### Konfigurasi Pengulangan

Konfigurasi perilaku pengulangan otomatis:

```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}
)
```

## Operasi Umum

### Buat Sesi Checkout

Hasilkan sesi checkout:

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

### Kelola Pelanggan

Buat dan ambil informasi pelanggan:

```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})"
```

### Tangani Langganan

Buat dan kelola langganan berulang:

```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` memerlukan setidaknya kode `country` ISO dua huruf. `customer` menerima `{ customer_id: "..." }` untuk melampirkan pelanggan yang sudah ada atau `{ email: "...", name: "..." }` untuk membuat pelanggan baru. `product_price` dalam denominasi mata uang terendah.
</Info>

## Pagination

### Auto-Pagination

Secara otomatis iterasi melalui semua halaman:

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

### Manual Pagination

Untuk kontrol lebih lanjut atas paginasi:

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

## Penanganan Kesalahan

Tangani berbagai kesalahan 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>
  Implementasikan logika retry dengan eksponensial backoff untuk kesalahan batasan jumlah agar aplikasi Anda dapat menangani skenario volume tinggi dengan lancar.
</Tip>

## Keamanan Tipe dengan Sorbet

Gunakan Sorbet untuk parameter permintaan yang aman tipe:

```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)
```

## Penggunaan Lanjutan

### Endpoint Tidak Terdokumentasi

Lakukan permintaan ke endpoint yang tidak terdokumentasi:

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

### Parameter Tidak Terdokumentasi

Kirim parameter yang tidak terdokumentasi:

```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])
```

## Integrasi Rails

### Buat Inisiator

Buat `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"
)
```

### Pola Objek Layanan

Buat layanan pembayaran:

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

### Integrasi Controller

Gunakan di controller Rails Anda:

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

## Integrasi Sinatra

Gunakan dengan aplikasi 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
```

## Sumber Daya

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-ruby">
    Lihat kode sumber dan ikut berkontribusi
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Dokumentasi lengkap API
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/bYqAp4ayYh">
    Dapatkan bantuan dan hubungi pengembang
  </Card>

  <Card title="Report Issues" icon="bug" href="https://github.com/dodopayments/dodopayments-ruby/issues">
    Laporkan bug atau minta fitur
  </Card>
</CardGroup>

## Dukungan

Butuh bantuan dengan Ruby SDK?

* **Discord**: Bergabunglah dengan [server komunitas](https://discord.gg/bYqAp4ayYh) kami untuk dukungan real-time
* **Email**: Hubungi kami di [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Buka masalah di [repository](https://github.com/dodopayments/dodopayments-ruby)

## Kontribusi

Kami menyambut kontribusi! Periksa [panduan kontribusi](https://github.com/dodopayments/dodopayments-ruby/blob/main/CONTRIBUTING.md) untuk memulai.