React Native

Đây là React Native checkout SDK chính thức của Dodo Payments, @dodopayments/react-native-checkout. SDK mở hosted checkout của Dodo trong một chế độ xem trình duyệt native và trả về một kết quả có kiểu. Lưu ý: có một package cũ, không liên quan tên là dodopayments-react-native-sdk (không có scope) với API hoàn toàn khác. Trang này chỉ mô tả package chính thức hiện tại có scope.

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 bước này vào toàn bộ quy trình thanh toán trên thiết bị di động.

React Native SDK là một lớp bao bọc Turbo Module mỏng trên cùng các core native Swift và Kotlin. SDK mở SFSafariViewController trên iOS và Chrome Custom Tab trên Android, không chứa 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à lấy return URL.

SDK này chỉ yêu cầu New Architecture, React Native 0.76+, iOS 16+ và Android minSdk 24.

Cài đặt

Install the Package

Android
iOS
Expo

Package được autolink và kéo com.dodopayments.api:checkout-android từ Maven.

npm i @dodopayments/react-native-checkout

Không cần thiết lập bổ sung; dependency native được tự động phân giải.

npm i @dodopayments/react-native-checkout
cd ios && pod install

Swift core được đóng gói trong package và cài đặt thông qua CocoaPods.

Chỉ dành cho development builds (không phải Expo Go).

npm i @dodopayments/react-native-checkout

Sau đó cấu hình app.json (xem phần Đăng ký Callback URL Scheme bên dưới).

Ứng dụng của bạn phải đăng ký một URL scheme để nhận return URL từ checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

Trong android/app/build.gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

Thay "myapp" bằng scheme của ứng dụng.

Trong ios/YourApp/Info.plist:

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 mục này thông qua giao diện Info → URL Types của Xcode.

Plugin cấu hình của package sẽ đăng ký scheme cho cả hai nền tảng tại prebuild. Truyền cho plugin một tùy chọn scheme trong app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme phải khớp với giá trị bạn truyền dưới dạng returnUrl (ví dụ: myappcheckout://return), và phải khác với expo.scheme. Expo đã đăng ký scheme đó trên MainActivity, và việc sử dụng lại có thể chuyển hướng lần quay lại từ checkout đến sai màn hình.Build lại dự án native sau khi chỉnh sửa app.json:

npx expo prebuild --clean

Tính năng này chỉ hoạt động với development builds, không hoạt động với Expo Go.Nếu android/app/build.gradle được duy trì thủ công và không có block defaultConfig { } tiêu chuẩn để plugin tìm thấy, hãy tự thêm placeholder thay thế. Xem tab Android ở trên.

Cách sử dụng

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

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

Chuyển tiếp Return URL

Listener Linking là bắt buộc để xử lý return URL trên iOS. Trên Android, handleOpenURL không thực hiện thao tác nào và resolve false vì Android core tự xử lý redirect. Bạn có thể đăng ký listener vô điều kiện trên cả hai nền tảng.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Ý nghĩa của kết quả

result.status là gợi ý UI, không phải bằng chứng thanh toán thành công. Hãy 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 mục Verify the Payment bên dưới.

string

Được thiết lập cho các checkout đăng ký.

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.

Record<string, string>

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

Xác minh khoản thanh toán

Webhooks

Dodo Payments gọi backend của bạn khi khoản 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ự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 khoản thanh toán, tuyệt đối không chỉ dựa vào result.status.

Tùy chỉnh giao diện

Tùy chỉnh thanh công cụ, các nút và bảng màu của trình duyệt checkout thông qua customization trên start(...). Các tùy chọn được nhóm theo nền tảng vì Custom Tab của Android và SFSafariViewController của iOS cung cấp các điều khiển native khác nhau. Tất cả các trường đều không bắt buộc; nếu bỏ qua customization, giao diện mặc định của từng nền tảng sẽ được sử dụng.

Android — Custom Tab

Màu nền của thanh công cụ.

Màu thanh điều hướng.

Màu đường phân cách phía trên thanh điều hướng.

'default' | 'back'

default hiển thị biểu tượng hệ thống “X”; back thay vào đó hiển thị mũi tên quay lại.

'start' | 'end'

Nút đóng xuất hiện ở phía nào của thanh công cụ.

Hiển thị biểu tượng chia sẻ của thanh công cụ.

boolean

Hiển thị tiêu đề trang bên dưới URL trong thanh công cụ.

boolean

Cho phép thanh công cụ tự động ẩn khi cuộn trang.

boolean

Hiển thị “Bookmark this page” trong menu thêm.

boolean

Hiển thị “Download page” trong menu thêm.

'system' | 'light' | 'dark'

Buộc sử dụng giao diện sáng hoặc tối bất kể cài đặt hệ thống của thiết bị.

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Nhãn hoặc biểu tượng cho nút đóng.

'pageSheet' | 'fullScreen'

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

boolean

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

'system' | 'light' | 'dark'

Buộc sử dụng giao diện sáng hoặc tối bất kể cài đặt hệ thống của thiết bị.

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Lỗi

start từ chối với một CheckoutError chỉ 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 bao giờ là một exception.

INVALID_CHECKOUT_URL: không phải là URL phiên checkout.dodopayments.com.
INVALID_RETURN_URL: không phải là absolute URL hợp lệ.
ALREADY_IN_PROGRESS: một checkout đang chạy.
PLATFORM_ERROR: lỗi nền tảng không mong đợi.

Phiên bị bỏ dở

Nếu ứng dụng hoặc JS bundle bị dừng giữa chừng trong quá trình checkout, promise sẽ bị mất nhưng native layer vẫn giữ phiên. Khôi phục phiên ở lần mount tiếp theo và đối soát phiên với backend của bạn.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await 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 kết quả

Xác minh khoản thanh toán

Webhooks

Get Payment Detail

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Cài đặt

​Cách sử dụng

​Chuyển tiếp Return URL

​Ý nghĩa của kết quả

​Xác minh khoản thanh toán

Webhooks

Get Payment Detail

​Tùy chỉnh giao diện

​Lỗi

​Phiên bị bỏ dở

​Liên quan

Mobile Integration Guide

Expo Boilerplate

Cài đặt

Cách sử dụng

Chuyển tiếp Return URL

Ý nghĩa của kết quả

Xác minh khoản thanh toán

Tùy chỉnh giao diện

Lỗi

Phiên bị bỏ dở

Liên quan