이 페이지에서는 Swift용 공식 Dodo Payments iOS checkout SDK를 다룹니다. 이 SDK는 네이티브 브라우저 뷰에서 Dodo Payments hosted checkout을 열고 typed result를 반환합니다.
Checkout Sessions API
이 SDK가 여는
checkout_url를 백엔드에서 생성합니다.Mobile Integration Guide
이 SDK가 전체 모바일 결제 흐름에서 어떻게 사용되는지 확인하세요.
SFSafariViewController에서 열고, 고객이 checkout을 완료하거나 나가면 typed CheckoutResult를 반환합니다. 이 SDK는 API key를 보유하지 않으며 networking code도 포함하지 않으므로 Dodo Payments API를 호출하지 않습니다. Checkout은 브라우저 뷰에서 실행됩니다. SDK는 해당 뷰를 표시하고 닫으며, return URL에서 result를 읽습니다.
Requirements: iOS 16 이상 및 Swift 6.2 이상(패키지는 swift-tools-version: 6.2를 선언합니다). SDK에는 third-party dependencies가 없습니다.
설치
1
Add the Package
Xcode에서 File → Add Package Dependencies로 이동한 다음 package URL을 입력합니다:버전 1.1.0 이상을 선택합니다. Appearance customization에는 1.1.0이 필요합니다.대신 라이브러리 product는
Package.swift에서 패키지를 추가하려면 다음 dependency를 추가합니다:Package.swift
DodoCheckout입니다.2
Register a Callback URL Scheme
iOS가 checkout의 return URL을 앱으로 다시 라우팅할 수 있도록 URL scheme을 등록합니다. Xcode의 Info → URL Types에서 URL type을 추가할 수도 있습니다.SDK에 전달하는
Info.plist에 URL type을 추가합니다:Info.plist
returnUrl에서 이 scheme을 사용합니다. 예를 들어 myapp://checkout/return을 사용하고, 백엔드에서 session을 생성할 때 checkout session의 return_url에도 동일한 URL을 설정합니다. SDK는 scheme, host, path를 기준으로 return URL을 일치시킵니다. URL이 실제 페이지를 로드할 필요는 없습니다.사용법
DodoCheckout.start는 main actor에서 실행되는 async 함수입니다. 백엔드가 반환하는 checkout_url로 생성한 URL를 checkoutUrl로 전달합니다:
onEvent는 .opened, .returnReceived 및 .closed events를 수신합니다. 해당 events의 name 값은 checkout.opened, checkout.return_received 및 checkout.closed입니다. events는 logging에만 사용하고 결과를 결정하는 데 사용하지 마세요.
Return URL 전달
SFSafariViewController는 자체 return URL을 가로챌 수 없으므로 iOS가 대신 앱에서 URL을 엽니다. 들어오는 모든 URL을 DodoCheckout.handleOpenURL(_:)로 전달합니다. scenes를 사용하지 않는 앱에서는 app delegate의 application(_:open:options:)에서 이를 호출합니다.
- SwiftUI
- SceneDelegate
모든 URL을 전달할 수 있습니다.
handleOpenURL는 진행 중인 checkout의 returnUrl와 일치하는 URL에서만 작동하며, 해당 URL에 대해 true를 반환합니다. 그 외의 URL에는 false를 반환하므로 해당 URL을 직접 처리하세요.Result의 의미
SDK는 return URL의 query parameters에서CheckoutResult를 생성합니다.
CheckoutStatus
필수
다섯 가지 값 중 하나입니다:
succeeded: return URL에status=succeeded(일회성 결제) 또는status=active(subscription)이 있습니다.failed: 결제가 거부되었습니다(status=failed).cancelled: return URL이 도착하기 전에 고객이 sheet를 닫았습니다. SDK는 결과를 알 수 없으며 결제가 성공했을 수도 있으므로 failure screen을 표시하지 마세요. 대신 abandoned session을 reconcile하세요.pending: 결제가 나중에 처리됩니다(status=processing또는 모든requires_*값). 또는statusparameter가 없거나 인식되지 않았습니다.cancelled와 동일하게 reconcile하세요.expired: checkout session이 만료되었습니다(status=expired).
String?
return URL에
payment_id query parameter가 포함된 경우의 값입니다. UI에 표시하되 access를 부여하는 데 사용하지 마세요. Verify the Payment을 참고하세요.String?
subscription_id query parameter입니다. subscription checkouts에 설정됩니다.[String]?
license_key query parameter입니다. checkout에 license key products가 포함된 경우 설정됩니다.String?
email query parameter입니다. checkout에서 email address를 수집할 때 설정됩니다.[String: String]
return URL의 모든 query parameter를 그대로 포함합니다.
결제 확인
Webhooks
결제가 성공하거나 subscription이 활성화되면 Dodo Payments가 백엔드를 호출합니다.
Get Payment Detail
secret key를 사용해
paymentId를 조회하여 상태를 확인합니다.result.status만 신뢰하지 마세요.
Appearance Customization
sheet의 dismiss button, presentation style 및 color scheme을 변경하려면BrowserCustomization를 customization로 전달하여 start(...)에 설정합니다. 모든 field는 optional입니다. nil field의 경우 SDK가 해당 option을 설정하지 않으며 iOS가 자체 default를 적용합니다. 예외는 presentationStyle이며, 여기서 nil는 pageSheet를 의미합니다.
DismissButtonStyle?
dismiss button의 style입니다:
done, close 또는 cancel입니다. label로 렌더링할지 icon으로 렌더링할지는 iOS가 결정합니다.PresentationStyle?
pageSheet(default)는 고객이 아래로 swipe하여 dismiss할 수 있는 card를 표시합니다. fullScreen는 전체 화면을 덮으며 dismiss gesture가 없습니다.Bool?
페이지를 scroll할 때 toolbar가 collapse되도록 합니다.
presentationStyle가 fullScreen일 때만 시각적 효과가 있습니다. pageSheet에서는 이 설정과 관계없이 bars가 고정됩니다.ColorScheme?
light 또는 dark는 device의 system setting과 관계없이 해당 appearance를 강제합니다. system는 system setting을 따릅니다. 이 option은 페이지 주변의 native controls만 theme으로 지정합니다. checkout page 자체의 light 또는 dark mode는 checkout session의 customization.theme에서 결정되며, 색상은 customization.theme_config에서 가져옵니다.SFSafariViewController tint properties는 iOS 26부터 deprecated되었습니다.
Errors
start는 misuse 또는 platform failure가 발생한 경우에만 CheckoutError를 throw합니다. error.code에서 reason을 읽으세요. 고객의 취소 또는 결제 거부는 항상 result이며 throw된 error가 아닙니다.
invalidCheckoutUrl(INVALID_CHECKOUT_URL):checkoutUrl가checkout.dodopayments.com또는test.checkout.dodopayments.com의/session/로 시작하는 올바른 checkout session URL이 아닙니다.invalidReturnUrl(INVALID_RETURN_URL):returnUrl가 scheme과 host가 있는 absolute URL이 아닙니다.alreadyInProgress(ALREADY_IN_PROGRESS): 다른 checkout이 실행 중입니다. 한 번에 하나의 checkout만 실행할 수 있습니다.platformError(PLATFORM_ERROR): 표시할 view controller가 없는 경우와 같은 예기치 않은 platform failure입니다.
alreadyInProgress입니다. 이때 찾은 record는 여전히 실행 중인 checkout에 속합니다.
Abandoned Sessions
SDK는 checkout을 표시할 때 checkout session을 기록하고, checkout이
succeeded, failed 또는 expired로 종료될 때만 record를 삭제합니다. checkout 중 앱이 종료되거나 cancelled 또는 pending result가 반환된 후에도 record는 유지됩니다. 다음 launch 시점과 cancelled 또는 pending result가 반환될 때마다 이를 확인하세요.abandoned.sessionId는 cks_로 시작하는 checkout session ID입니다. abandoned.createdAt는 checkout이 시작된 Date입니다. 백엔드에서는 Get Checkout Session을 사용해 session을 조회할 수 있으며, 이 endpoint는 payment_id와 payment_status를 반환합니다. 결제가 최종 status에 도달할 때까지는 실패가 아닌 pending으로 처리하세요.
관련 항목
Mobile Integration Guide
Android, React Native 및 Flutter에서 동일한 contract를 제공합니다.
React Native SDK
iOS에서 동일한 Swift core를 래핑합니다.