net/http와 connection pool을 사용해 요청을 전송하고, 실패한 요청을 재시도하며, 페이지가 매겨진 목록을 자동으로 순회하고, RBI 및 RBS type definitions를 제공합니다.
설치
Gemfile에 gem을 추가하세요:Gemfile
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"에서만 작동합니다.
핵심 기능
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를 설정하세요:
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하세요:
고객 관리
email address와 name으로 고객을 생성한 다음 ID로 조회하세요:Subscription 처리
subscription을 생성하고, on-demand subscription에 요금을 청구하고, subscription의 metadata를 업데이트합니다.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를 발생시킵니다:
status, headers, body attribute가 있습니다:
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에 대한 도움이 필요하면 다음을 이용하세요:- Discord: 실시간 지원을 받으려면 community server에 참여하세요.
- Email: support@dodopayments.com으로 문의하세요.
- GitHub: repository에 issue를 등록하세요.