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
npx expo install expo-build-properties

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

Trong app.json:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "manifestPlaceholders": {
              "dodoCallbackScheme": "myapp"
            }
          }
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [
          {
            "CFBundleURLSchemes": ["myapp"]
          }
        ]
      }
    }
  }
}

Package cũng đi kèm một plugin cấu hình Expo @dodopayments/react-native-checkout, nhưng hiện tại plugin không ghi URL scheme và cũng không ghi manifest placeholder. Chỉ thêm plugin này sẽ không đăng ký callback scheme — hãy sử dụng cấu hình expo-build-properties và infoPlist ở trên.

Build lại native project 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 phải Expo Go.

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 xử lý redirect một cách native. Bạn có thể đăng ký listener này 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 Result

result.status là một gợi ý UI, không phải bằng chứng thanh toán. Xác nhận mọi payment 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 đặt 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 Xác minh Payment bên dưới.

string

Được đặt cho subscription checkout.

string[]

Được đặt khi checkout bao gồm các sản phẩm license key.

string

Được đặt khi checkout thu thập email.

Record<string, string>

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

Xác minh Payment

Webhooks

Dodo Payments gọi backend của bạn khi payment 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 bước xác nhận payment này hoàn tất, tuyệt đối không chỉ dựa vào result.status.

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. Payment bị hủy hoặc bị từ chối luôn được trả về dưới dạng result, không phải exception.

INVALID_CHECKOUT_URL: không phải session URL của checkout.dodopayments.com.
INVALID_RETURN_URL: không phải absolute URL hợp lệ.
ALREADY_IN_PROGRESS: checkout đang chạy.
PLATFORM_ERROR: lỗi nền tảng không mong đợi.

Session 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ữ session. Khôi phục session ở lần mount tiếp theo và đối soát 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 Result

Xác minh Payment

Webhooks

Get Payment Detail

Lỗi

Session 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 Result

​Xác minh Payment

Webhooks

Get Payment Detail

​Lỗi

​Session 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 Result

Xác minh Payment

Lỗi

Session bị bỏ dở

Liên quan