Skip to main content
Ruby SDK를 사용하면 Ruby 애플리케이션에서 Dodo Payments REST API에 액세스할 수 있습니다. 표준 라이브러리의 net/http와 connection pool을 사용해 요청을 전송하고, 실패한 요청을 재시도하며, 페이지가 매겨진 목록을 자동으로 순회하고, RBI 및 RBS type definitions를 제공합니다.

설치

Gemfile에 gem을 추가하세요:
Gemfile
SDK 릴리스에는 API 변경 사항에 대한 지원이 추가됩니다. 최신 상태를 유지하려면 bundle update dodopayments를 정기적으로 실행하세요.
그런 다음 설치하세요:
SDK에는 Ruby 3.2.0 이상이 필요합니다.

빠른 시작

client를 생성한 다음 checkout session을 생성하세요:
bearer_token를 생략하면 client가 DODO_PAYMENTS_API_KEY 환경 변수를 읽습니다. environment를 생략하면 client가 live mode에 연결됩니다. test mode API key는 environment: "test_mode"에서만 작동합니다.
API key는 환경 변수나 secrets manager에 보관하세요. version control에 커밋하거나 코드에 노출하지 마세요.

핵심 기능

Ruby Conventions

Snake_case method와 keyword argument를 사용하며, 중첩된 parameter에는 일반 hash도 사용할 수 있습니다.

Elegant Syntax

Response는 attribute reader를 제공하는 object이며, obj[:prop]를 사용하면 SDK에 정의되지 않은 field도 읽을 수 있습니다.

Auto-Pagination

auto_paging_each는 모든 item을 순회하고 필요할 때 다음 page를 가져옵니다.

Type Safety

Sorbet용 RBI definition을 제공하며 sorbet-runtime에 의존하지 않습니다.

Configuration

Dodopayments::Client.new는 bearer_token, webhook_key, environment, base_url, max_retries, timeout, initial_retry_delay, max_retry_delay를 받습니다. 이 값을 생략하면 환경에서 DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY(웹훅 signing secret), DODO_PAYMENTS_BASE_URL를 읽습니다. client는 thread-safe하며 자체 connection pool을 유지하므로, 애플리케이션에 client 하나를 생성하고 재사용하세요. 웹훅을 확인하려면 원시 request body와 header를 dodo_payments.webhooks.unwrap(payload, headers: headers)에 전달하세요. 이 함수는 webhook key로 signature를 확인하고 parsing된 event를 반환합니다. dodo_payments.webhooks.unsafe_unwrap(payload)는 확인 없이 body를 parsing하므로 testing 용도로만 사용하세요. Webhooks를 참조하세요.

Timeout Configuration

요청은 기본적으로 60초 후 timeout됩니다. client 또는 단일 request에서 초 단위로 timeout를 설정하세요:
request가 timeout되면 SDK는 Dodopayments::Errors::APITimeoutError를 발생시킵니다. timeout된 request는 기본적으로 재시도됩니다.

Retry Configuration

SDK는 connection error, timeout, 그리고 status가 408, 409, 429 또는 500 이상인 response를 재시도합니다. 기본적으로 짧은 exponential backoff를 적용해 두 번 재시도합니다. client 또는 단일 request에서 max_retries를 설정하세요:

일반적인 작업

이 섹션의 예제에서는 Quick Start의 dodo_payments client를 사용합니다.

Checkout Session 생성

checkout session을 생성한 다음 고객을 반환된 checkout_url로 redirect하세요:
각 checkout URL은 한 번만 사용할 수 있으며 24시간 후 만료됩니다. 모든 session option은 Checkout Sessions을 참조하세요.

고객 관리

email address와 name으로 고객을 생성한 다음 ID로 조회하세요:

Subscription 처리

subscription을 생성하고, on-demand subscription에 요금을 청구하고, subscription의 metadata를 업데이트합니다.
POST /subscriptions(SDK의 subscriptions.create method)는 deprecated입니다. 기존 integration에서는 계속 작동하지만, 새 integration에서는 Checkout Session을 통해 subscription을 생성해야 합니다.
billing에는 두 글자 ISO 국가 코드인 country만 필요합니다. customer에 { customer_id: "..." }를 전달하면 기존 고객을 연결하고, { email: "...", name: "..." }를 전달하면 고객을 생성합니다. charge는 on-demand subscriptions에 사용하며, product_price는 통화의 최소 단위입니다.

Pagination

Auto-Pagination

List method는 page를 반환합니다. 현재 page는 items를 읽고, 모든 item을 순회하려면 auto_paging_each를 호출하세요. 필요할 때 다음 page를 가져옵니다:

Manual Pagination

한 번에 한 page씩 이동하려면 next_page?와 next_page를 호출하세요:

Error Handling

SDK가 API에 연결하지 못하거나 API가 4xx 또는 5xx status를 반환하면 SDK는 Dodopayments::Errors::APIError의 subclass를 발생시킵니다:
error class는 원인에 따라 달라집니다. 각 error에는 status, headers, body attribute가 있습니다:
SDK는 이미 exponential backoff를 사용해 429 response를 재시도합니다. RateLimitError는 이러한 재시도도 실패했다는 의미이므로, request를 다시 보내기 전에 더 오래 기다리세요.

Sorbet을 사용한 Type Safety

SDK는 RBI definition을 제공하며 sorbet-runtime에 의존하지 않습니다. type-checked request parameter를 사용하려면 hash 대신 model class를 전달하세요:

고급 사용법

문서화되지 않은 Endpoint

SDK method가 없는 endpoint를 호출하려면 request를 사용하세요. SDK method와 동일한 authentication 및 retry를 적용합니다:

문서화되지 않은 Parameter

SDK에 정의되지 않은 parameter를 전송하려면 request_options에 전달하세요. 문서화된 parameter와 이름이 같은 extra_* parameter는 해당 값을 override합니다:

Rails Integration

Initializer 생성

Rails가 시작될 때 config/initializers/dodo_payments.rb에서 client 하나를 생성하세요:

Service Object Pattern

client를 service object로 감싸세요:

Controller Integration

controller에서 service를 호출하고 checkout page로 redirect하세요:

Sinatra Integration

configure block에서 client를 한 번 생성하고 route에서 사용하세요:

리소스

GitHub Repository

소스 코드, 릴리스 및 전체 method 목록입니다.

API Reference

모든 endpoint, parameter 및 response입니다.

Discord Community

질문하고 다른 개발자와 소통하세요.

Report Issues

bug를 신고하거나 feature를 요청하세요.

Support

Ruby SDK에 대한 도움이 필요하면 다음을 이용하세요:

Contributing

기여하려면 contributing guidelines를 읽어보세요.
마지막 수정일 2026년 9월 26일