Tích hợp Mobile SDK

Tapaya Accept SDK tích hợp việc xử lý thanh toán bằng thẻ trực tiếp vào ứng dụng của bạn. SDK được cung cấp cho Android (Kotlin) và cho React Native / Expo, cả hai đều chạy trên thiết bị Android. Gói React Native là một lớp bọc mỏng bên ngoài Android SDK, nên các bề mặt API, kiểu dữ liệu và trường hợp lỗi bên dưới đều giống nhau trên cả hai.

Mọi mẫu mã trên trang này đều được chia tab theo ngôn ngữ. Chọn một ngôn ngữ và toàn bộ trang sẽ chuyển theo.

Cài đặt

dependencies {
    implementation("com.tapaya:accept:1.15.0")
}

Android: thêm dependency vào build.gradle.kts ở cấp module, sau đó đồng bộ dự án.

React Native: cài đặt bằng npx expo install @tapayadot/accept-react-native, thêm config plugin như minh họa, sau đó tạo lại dự án native bằng npx expo prebuild --clean và chạy dự án bằng npx expo run:android.

Khởi tạo

Accept là điểm truy cập cho mọi chức năng của SDK. Khởi tạo nó một lần khi ứng dụng khởi động (trên Android, thường là trong lớp Application của bạn), sau đó xác thực riêng bằng token của merchant.

Bước 1: Khởi tạo

// Sandbox is the default (isProduction = false)
Accept.initialize(context = this)

// Target production explicitly
Accept.initialize(context = this, isProduction = true)

// Or drive it from your build type
Accept.initialize(context = this, isProduction = !BuildConfig.DEBUG)

Trên React Native không có context; native module giữ nó thay cho bạn.

Bước 2: Xác thực

Gọi Accept.auth.authenticate() sau khi khởi tạo để đăng nhập merchant bằng token lấy từ backend của bạn. Hàm này là bất đồng bộ và thất bại với một lỗi SDK. Khi thành công, trạng thái SDK chuyển thành authenticated (đã đăng nhập).

// suspend; call from a coroutine
try {
    val sdkToken = myBackendApi.getSdkToken()
    Accept.auth.authenticate(sdkToken)
    // Accept.state now emits SdkState.Authenticated
} catch (e: AcceptException) {
    // handle authentication failure
}

Theo dõi vòng đời để phản hồi các chuyển đổi trạng thái sau: idle → initialized → authenticated.

// Accept.state is a StateFlow<SdkState>
Accept.state.collect { state ->
    if (state == SdkState.Authenticated) loadMerchant()
}

Khái niệm cốt lõi

Đối tượng Accept cung cấp SDK thông qua một nhóm nhỏ các bề mặt API:

Nhận thanh toán

Gọi Accept.payments.pay() với số tiền (theo đơn vị nhỏ nhất của loại tiền tệ) và mã tiền tệ ISO 4217, sau đó theo dõi luồng các sự kiện PaymentEvent mà nó báo về: đầu tiên là tiến trình, sau đó là kết quả cuối cùng. pay() không bao giờ ném ngoại lệ; thay vào đó, việc không tạo được khoản thanh toán được báo về dưới dạng sự kiện CreationFailed.

Điểm khác biệt duy nhất là cách bạn theo dõi luồng đó: Kotlin trả về một Flow<PaymentEvent> để bạn collect từ một coroutine, còn React Native nhận một listener và trả về một subscription mà bạn có thể remove().

amount và currency là bắt buộc. Với các tham số tùy chọn (paymentToken, receiptConfig, nfcPosition, metadata, tip, transactionTimeout, display), xem Tạo khoản thanh toán.

Accept.payments.pay(amount = 15000, currency = "CZK") // 150.00 Kč
    .collect { event ->
        when (event) {
            PaymentEvent.Creating -> Log.d("pay", "creating")
            is PaymentEvent.Created -> Log.d("pay", "created ${event.paymentToken}")
            PaymentEvent.Launched -> Log.d("pay", "launched")
            is PaymentEvent.Result -> Log.d("pay", event.payResult.toString())
            is PaymentEvent.CreationFailed -> Log.e("pay", event.cause.toString())
        }
    }

Sự kiện kết quả cuối cùng mang một PayResult: thành công (với paymentToken, metadata, authCode, receiptDetails), bị từ chối (metadata, receiptDetails), bị hủy (metadata) hoặc thất bại (reason, metadata). Kotlin mô hình hóa chúng thành các lớp con PayResult.Success / Declined / Canceled / Failed; React Native mô hình hóa chúng thành một discriminated union mà bạn rẽ nhánh bằng payResult.type === 'success'. Xem Kết quả thanh toán để biết chi tiết đầy đủ. Truy vấn khoản thanh toán sau đó bằng Accept.payments.status(paymentToken), dừng nó bằng Accept.payments.cancel(paymentToken), hoặc hoàn tiền bằng Accept.payments.refund(paymentToken, reason).

Chỉ lấy kết quả (React Native)

Nếu UI của bạn không hiển thị các trạng thái trung gian, payAsync() rút gọn toàn bộ luồng thành PayResult cuối cùng và reject với một AcceptError cho mọi trường hợp mà pay() lẽ ra đã báo là creationFailed. Hàm này không có phiên bản tương ứng trên Kotlin; ở đó hãy collect Flow, hoặc chỉ lấy sự kiện cuối cùng của nó.

const result = await Accept.payments.payAsync({ amount: 15000, currency: 'CZK' });
if (result.type === 'success') {
    console.log(result.paymentToken, result.receiptUrl);
}

Thông tin merchant và SDK

Accept.merchant cung cấp hồ sơ và cấu hình thanh toán của merchant đã đăng nhập. Accept.sdk cung cấp thông tin về bản build SDK và thiết bị này. Mọi thành phần bên dưới đều yêu cầu gọi Accept.initialize() trước (ngoại trừ Accept.sdk.version), và mọi thành phần của Accept.merchant còn yêu cầu thêm Accept.auth.authenticate() đã hoàn tất, nếu không lời gọi sẽ ném NotInitialized hoặc NotAuthenticated.

Merchant

val info = Accept.merchant.info()                      // MerchantInformation?
val config = Accept.merchant.config()                  // MerchantConfig
val currencies = Accept.merchant.availableCurrencies() // List<String>
val status = Accept.merchant.onboardingStatus()        // OnboardingStatus

Cả bốn đều là hàm suspend và ném NotAuthenticated, NoInternetConnection hoặc Unknown khi thất bại.

MerchantInformation chứa hồ sơ doanh nghiệp đã đăng ký. Luôn có: merchantId (UUID), email, businessType (BusinessType), legalName, registrationNumber, mcc và địa chỉ đã đăng ký (addressLine1, city, country). Tùy chọn (null trừ khi merchant đã cung cấp): vatNumber, incorporationDate, addressLine2, postalCode, state, phone, averageItemValue, expectedMonthlyTurnover, businessModelDescription, numberOfEmployees, annualTurnover, balanceSheetTotal, statementDescriptor, termsVersion.

BusinessType là một trong các giá trị INDIVIDUAL, COMPANY, NONPROFIT_ORGANIZATION, GOVERNMENT_ENTITY hoặc PARTNERSHIP.

MerchantConfig chứa availableCurrencies: List<String> và currency: String? mặc định của merchant.

OnboardingStatus là một sealed interface: hoặc là ReadyForPayments, hoặc là RequiresAction(state), trong đó state là một OnboardingState: NOT_STARTED, PENDING, ACTIVE, ATTENTION_NEEDED, ACTION_REQUIRED, BLOCKED, WAITING_FOR_KYB, WAITING_FOR_STAKEHOLDERS hoặc PENDING_ACQUIRER_APPROVAL. Xem Onboarding merchant để biết ý nghĩa của từng trạng thái.

SDK

Accept.sdk.version            // String, e.g. "1.15.0"
Accept.sdk.isProduction       // Boolean
Accept.sdk.deviceId()         // String?  (suspend)
Accept.sdk.minimumAmounts()   // List<MinimumAmount>  (suspend)

Ứng dụng plugin

Mọi khoản thanh toán bằng thẻ đều được chuyển cho Tapaya Terminal, ứng dụng plugin của Tapaya; ứng dụng này luôn bắt buộc, không có luồng thanh toán bằng thẻ nào bỏ qua nó. Kiểm tra xem ứng dụng đã được cài đặt chưa, sau đó kích hoạt máy thanh toán, hoặc mở trang ứng dụng trên cửa hàng để merchant có thể cài đặt.

Dùng Accept.plugin.isInstalled(), Accept.plugin.activateTerminal() và Accept.plugin.install() cho việc này. Xem Cài đặt và kích hoạt máy thanh toán để biết mã và mọi kết quả kích hoạt.

Đọc trạng thái hiện tại của plugin bằng Accept.plugin.status(), hoặc đăng xuất merchant khỏi plugin bằng Accept.plugin.logout().

Quyền truy cập

Thanh toán bằng thẻ yêu cầu ứng dụng chủ có quyền truy cập vị trí (ACCESS_FINE_LOCATION). SDK không yêu cầu quyền này thay bạn; hãy cấp quyền bằng các API quyền tiêu chuẩn của Android trước khi gọi pay().

class PaymentActivity : AppCompatActivity() {
    private val requestLocation = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (granted) launchPaymentFlow() else showPermissionRationale()
    }

    fun startPayment() {
        requestLocation.launch(Manifest.permission.ACCESS_FINE_LOCATION)
    }
}

Nếu thiếu quyền vị trí hoặc không xác định được vị trí khi pay() chạy, flow sẽ phát ra PaymentEvent.CreationFailed với nguyên nhân là LocationPermissionRequired, LocationUnavailable hoặc LocationTimeout.

Xử lý lỗi

Mọi lỗi được kiểm soát đều mang một trong các tên dưới đây. Trên Kotlin, mỗi lỗi là một lớp con của sealed class AcceptException; trên React Native, tất cả đều là một lớp AcceptError duy nhất có code chứa tên lỗi, còn các trường payload (minimum, currency, state, …) nằm ngay trên cùng đối tượng đó.

Các lời gọi bất đồng bộ (authenticate, merchant.*, payments.status/cancel/refund, plugin.activateTerminal/status/logout/updateInfo, clear) thất bại với một trong các lỗi này. payments.pay() là ngoại lệ: hàm này không bao giờ ném lỗi, và báo các lỗi tương tự dưới dạng sự kiện CreationFailed mang theo nguyên nhân.

Các loại exception

Xử lý exception

Bọc lời gọi trong try/catch và rẽ nhánh theo các trường hợp cụ thể mà bạn xử lý, với một nhánh catch tổng quát làm phương án dự phòng. Kotlin rẽ nhánh theo lớp con exception; React Native kiểm tra bằng AcceptError.is() và dùng switch trên code.

try {
    val status = Accept.payments.status(paymentToken)
} catch (e: SessionExpired) {
    // Re-authenticate
} catch (e: NoInternetConnection) {
    // Ask the user to check connectivity
} catch (e: AcceptException) {
    // Handle any other SDK error
    Log.e("Payment", "Error: ${e.message}")
}

Ghi log

Bật log gỡ lỗi trong quá trình phát triển để khắc phục sự cố.

Accept.setDebugLoggingEnabled(true)

Đăng xuất

Xóa toàn bộ trạng thái SDK được lưu cục bộ (auth token, device id, cấu hình đã lưu đệm) và đặt lại trạng thái SDK về idle. Gọi hàm này khi người dùng đăng xuất. Để đồng thời đăng xuất merchant khỏi ứng dụng Tapaya Terminal, hãy gọi Accept.plugin.logout() trước.

Accept.plugin.logout() // suspend; signs out of the Tapaya Terminal app
Accept.clear()         // suspend; clears local SDK state