Trang này trình bày iOS checkout SDK chính thức của Dodo Payments dành cho Swift. SDK mở hosted checkout của Dodo Payments trong chế độ xem trình duyệt gốc và trả về một kết quả có kiểu dữ liệu.
Checkout Sessions API
Tạo
checkout_url mà SDK này sẽ mở từ backend của bạn.Mobile Integration Guide
Tìm hiểu cách SDK này tích hợp vào toàn bộ quy trình thanh toán trên thiết bị di động.
SFSafariViewController và trả về một CheckoutResult có kiểu dữ liệu khi khách hàng hoàn tất hoặc rời checkout. SDK không chứa API key và không có mã networking, vì vậy không bao giờ gọi Dodo Payments API. Checkout chạy trong chế độ xem trình duyệt. SDK hiển thị và đóng chế độ xem đó, đồng thời đọc kết quả từ return URL.
Yêu cầu: iOS 16 trở lên và Swift 6.2 trở lên (package khai báo swift-tools-version: 6.2). SDK không có dependency bên thứ ba.
Cài đặt
1
Add the Package
Trong Xcode, đi đến File → Add Package Dependencies và nhập package URL:Chọn version 1.1.0 hoặc mới hơn. Tùy chỉnh giao diện yêu cầu version 1.1.0.Để thêm package trong Library product là
Package.swift, hãy thêm dependency này:Package.swift
DodoCheckout.2
Register a Callback URL Scheme
Đăng ký URL scheme để iOS định tuyến return URL của checkout trở lại ứng dụng của bạn. Thêm một URL type vào Bạn cũng có thể thêm URL type trong Xcode tại Info → URL Types.Sử dụng scheme này trong
Info.plist:Info.plist
returnUrl mà bạn truyền cho SDK, ví dụ myapp://checkout/return, và đặt cùng URL đó làm return_url của checkout session khi backend tạo session. SDK đối chiếu return URL theo scheme, host và path. URL không cần tải một trang thực.Cách sử dụng
DodoCheckout.start là một hàm async chạy trên main actor. Truyền checkoutUrl dưới dạng URL được tạo từ checkout_url mà backend trả về:
onEvent nhận các event .opened, .returnReceived và .closed. Các giá trị name của chúng lần lượt là checkout.opened, checkout.return_received và checkout.closed. Chỉ sử dụng event để ghi log, không bao giờ dùng chúng để quyết định kết quả.
Chuyển tiếp Return URL
SFSafariViewController không thể tự bắt return URL của nó, vì vậy iOS sẽ mở URL đó trong ứng dụng của bạn. Chuyển tiếp mọi URL đến DodoCheckout.handleOpenURL(_:). Trong ứng dụng không sử dụng scenes, hãy gọi hàm này từ application(_:open:options:) của app delegate.
- SwiftUI
- SceneDelegate
Bạn có thể chuyển tiếp mọi URL.
handleOpenURL chỉ hoạt động trên URL khớp với returnUrl của checkout đang diễn ra và trả về true cho URL đó. Với mọi URL khác, hàm trả về false, vì vậy hãy tự xử lý URL đó.Ý nghĩa của kết quả
SDK xây dựngCheckoutResult từ các query parameter trên return URL.
CheckoutStatus
bắt buộc
Một trong năm giá trị:
succeeded: return URL cóstatus=succeeded(thanh toán một lần) hoặcstatus=active(subscription).failed: thanh toán bị từ chối (status=failed).cancelled: khách hàng đóng sheet trước khi return URL xuất hiện. SDK không biết kết quả và thanh toán có thể đã thành công, vì vậy không hiển thị màn hình thất bại. Thay vào đó, hãy đối soát abandoned session.pending: thanh toán được quyết toán sau (status=processinghoặc bất kỳ giá trịrequires_*nào), hoặc parameterstatusbị thiếu hoặc không được nhận dạng. Hãy đối soát như vớicancelled.expired: checkout session đã hết hạn (status=expired).
String?
Query parameter
payment_id, khi return URL có parameter này. Hiển thị parameter này trong UI nhưng không dùng nó để cấp quyền truy cập. Xem Xác minh thanh toán.String?
Query parameter
subscription_id. Được thiết lập cho subscription checkout.[String]?
Query parameter
license_key. Được thiết lập khi checkout bao gồm các sản phẩm có license key.String?
Query parameter
email. Được thiết lập khi checkout thu thập địa chỉ email.[String: String]
Mọi query parameter từ return URL, được giữ nguyên.
Xác minh thanh toán
Webhooks
Dodo Payments gọi backend của bạn khi thanh toán thành công hoặc subscription được kích hoạt.
Get Payment Detail
Tra cứu
paymentId bằng secret key của bạn để kiểm tra trạng thái.result.status.
Tùy chỉnh giao diện
Để thay đổi nút đóng sheet, kiểu trình bày và bảng màu, hãy truyền mộtBrowserCustomization dưới dạng customization vào start(...). Mọi field đều không bắt buộc. Với field nil, SDK không thiết lập tùy chọn đó và iOS áp dụng giá trị mặc định của riêng mình. Ngoại lệ là presentationStyle, trong đó nil có nghĩa là pageSheet.
DismissButtonStyle?
Kiểu của nút đóng:
done, close hoặc cancel. iOS quyết định hiển thị nút dưới dạng nhãn hay biểu tượng.PresentationStyle?
pageSheet (mặc định) hiển thị một card mà khách hàng có thể vuốt xuống để đóng. fullScreen bao phủ toàn bộ màn hình và không có thao tác vuốt để đóng.Bool?
Cho phép toolbar thu gọn khi trang được cuộn. Tùy chọn này chỉ có hiệu lực khi
presentationStyle là fullScreen. Với pageSheet, các thanh luôn được ghim bất kể cài đặt này.ColorScheme?
light hoặc dark buộc giao diện đó được áp dụng bất kể cài đặt hệ thống của thiết bị. system tuân theo cài đặt hệ thống. Tùy chọn này chỉ áp dụng theme cho các control gốc xung quanh trang. Chế độ sáng hoặc tối của chính trang checkout lấy từ customization.theme trên checkout session, còn màu sắc lấy từ customization.theme_config.SFSafariViewController bên dưới đã bị deprecated kể từ iOS 26.
Lỗi
start chỉ ném CheckoutError khi sử dụng sai hoặc xảy ra lỗi nền tảng. Đọc nguyên nhân từ error.code. Khách hàng hủy hoặc thanh toán bị từ chối luôn là một result, không phải lỗi được ném ra.
invalidCheckoutUrl(INVALID_CHECKOUT_URL):checkoutUrlkhông phải là URL checkout session hợp lệ (path bắt đầu bằng/session/) trêncheckout.dodopayments.comhoặctest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlkhông phải là absolute URL có scheme và host.alreadyInProgress(ALREADY_IN_PROGRESS): một checkout khác đang chạy. Mỗi lần chỉ có thể chạy một checkout.platformError(PLATFORM_ERROR): lỗi nền tảng không mong đợi, chẳng hạn không có view controller để trình bày.
alreadyInProgress: record bạn tìm thấy khi đó thuộc về checkout vẫn đang chạy.
Abandoned session
SDK ghi lại checkout session khi trình bày checkout và chỉ xóa record khi checkout kết thúc với
succeeded, failed hoặc expired. Record vẫn còn khi ứng dụng bị đóng trong lúc checkout và sau result cancelled hoặc pending. Hãy kiểm tra record này ở lần khởi chạy tiếp theo và sau mỗi result cancelled hoặc pending.abandoned.sessionId là ID của checkout session, bắt đầu bằng cks_. abandoned.createdAt là Date mà checkout đã bắt đầu. Backend của bạn có thể tra cứu session bằng Get Checkout Session, API này trả về payment_id và payment_status của session. Cho đến khi thanh toán đạt trạng thái cuối cùng, hãy xem thanh toán là đang chờ xử lý, không phải thất bại.
Liên quan
Mobile Integration Guide
Cùng một contract cho Android, React Native và Flutter.
React Native SDK
Bọc cùng Swift core này trên iOS.