iOS

Đây là iOS checkout SDK chính thức của Dodo Payments dành cho Swift. SDK mở checkout được host của Dodo trong một chế độ xem trình duyệt native và trả về một kết quả có kiểu.

Checkout Sessions API

Tạo checkout_url mà SDK này sẽ mở từ backend của bạn.

Mobile Integration Guide

Xem cách tích hợp này vào toàn bộ quy trình thanh toán trên mobile.

iOS SDK mở checkout được host của Dodo trong SFSafariViewController, không lưu API key và không bao giờ gọi trực tiếp Dodo API. Toàn bộ logic checkout chạy trong trình duyệt; SDK chỉ quản lý vòng đời của view và bắt return URL. Yêu cầu iOS 16+, Swift 6.

Cài đặt

Add the Package

Trong Xcode, đi đến File → Add Package Dependencies và nhập:

https://github.com/dodopayments/dodopayments-mobile-sdk-ios

Chọn phiên bản 1.0.0 trở lên.Ngoài ra, thêm vào Package.swift của bạn:

Package.swift

.package(url: "https://github.com/dodopayments/dodopayments-mobile-sdk-ios", from: "1.0.0")

Ứng dụng của bạn phải đăng ký một URL scheme để nhận return URL từ checkout. Thêm nội dung này vào Info.plist của bạn:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Bạn cũng có thể thêm nội dung này thông qua giao diện Info → URL Types của Xcode.

Cách sử dụng

import DodoCheckout

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,   // from your backend's checkout session
    returnUrl: URL(string: "myapp://checkout/return")!,
    onEvent: { event in print(event.name) }  // logging only
)

switch result.status {
case .succeeded: showSuccess(result.paymentId)
case .failed:    showFailure()
case .cancelled: dismiss()
case .pending:   showPending()
case .expired:   showExpired()
}

Chuyển tiếp Return URL

SFSafariViewController không có cách nào trong tiến trình để tự bắt return URL. Ứng dụng của bạn phải chuyển tiếp các URL đến SDK.

SwiftUI
SceneDelegate

.onOpenURL { url in
    DodoCheckout.handleOpenURL(url)
}

SceneDelegate.swift

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    DodoCheckout.handleOpenURL(url)
}

Bạn có thể chuyển tiếp mọi URL tại đây một cách an toàn. handleOpenURL chỉ xử lý các URL khớp với returnUrl đã đăng ký của bạn và trả về false cho mọi URL khác.

Ý nghĩa của Result

result.status là gợi ý UI, không phải bằng chứng thanh toán. Xác nhận mọi khoản thanh toán từ backend của bạn thông qua webhook payment.succeeded / subscription.active.

CheckoutStatus

bắt buộc

Một trong các giá trị succeeded, failed, cancelled, pending, expired.

String?

Được thiết lập khi return URL có chứa giá trị này. Hiển thị giá trị trong UI, không dùng giá trị này để cấp quyền truy cập. Xem phần Verify the Payment bên dưới.

String?

Được thiết lập cho các checkout subscription.

[String]?

Được thiết lập khi checkout bao gồm các sản phẩm có license key.

String?

Được thiết lập khi checkout thu thập email.

[String: String]

Mọi query parameter từ return URL, được giữ nguyên.

Xác minh Payment

Webhooks

Dodo Payments gọi backend của bạn khi một khoản thanh toán thành công hoặc một 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ực tiếp trạng thái.

Chỉ cấp quyền truy cập sau khi một trong các cơ chế này xác nhận thanh toán, không bao giờ chỉ dựa vào result.status.

Tùy chỉnh giao diện

Tùy chỉnh nút đóng của sheet, kiểu hiển thị và bảng màu thông qua customization trên start(...). Tất cả các trường đều không bắt buộc; nếu bỏ qua customization, giao diện SFSafariViewController mặc định của iOS sẽ được sử dụng.

DismissButtonStyle

Nhãn hoặc biểu tượng cho nút đóng: done, close hoặc cancel.

PresentationStyle

pageSheet hiển thị dưới dạng thẻ với thao tác vuốt để đóng; fullScreen bao phủ toàn bộ màn hình.

Bool

Cho phép thanh công cụ thu gọn khi cuộn. Chỉ hiển thị khi presentationStyle là fullScreen — pageSheet giữ các thanh cố định bất kể cài đặt này.

ColorScheme

Buộc giao diện sáng hoặc tối bất kể cài đặt hệ thống của thiết bị: system, light hoặc dark.

let result = try await DodoCheckout.start(
    checkoutUrl: checkoutUrl,
    returnUrl: URL(string: "myapp://checkout/return")!,
    customization: BrowserCustomization(
        dismissButtonStyle: .close,
        presentationStyle: .fullScreen,
        colorScheme: .dark
    )
)

Lỗi

start chỉ ném CheckoutError khi sử dụng sai hoặc nền tảng gặp lỗi. Thanh toán bị hủy hoặc bị từ chối luôn là một kết quả, không phải một ngoại lệ.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): không phải là URL phiên checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): không phải là URL tuyệt đối hợp lệ.
alreadyInProgress (ALREADY_IN_PROGRESS): một phiên thanh toán đã đang chạy.
platformError (PLATFORM_ERROR): nền tảng gặp lỗi không mong muốn.

Phiên bị bỏ dở

Nếu ứng dụng bị tắt giữa quá trình thanh toán, hãy khôi phục phiên trong lần khởi chạy tiếp theo và đối soát phiên đó với backend của bạn.

import DodoCheckout

if let abandoned = DodoCheckout.getAbandonedSession() {
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession()
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Cài đặt

Cách sử dụng

Chuyển tiếp Return URL

Ý nghĩa của Result

Xác minh Payment

Webhooks

Get Payment Detail

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan

Mobile Integration Guide

React Native SDK

Checkout Sessions API

Mobile Integration Guide

​Cài đặt

​Cách sử dụng

​Chuyển tiếp Return URL

​Ý nghĩa của Result

​Xác minh Payment

Webhooks

Get Payment Detail

​Tùy chỉnh giao diện

​Lỗi

​Phiên bị bỏ dở

​Liên quan

Mobile Integration Guide

React Native SDK

Cài đặt

Cách sử dụng

Chuyển tiếp Return URL

Ý nghĩa của Result

Xác minh Payment

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan