Android

Overview

The Telr Mobile Payment SDK for Android is a comprehensive payment solution that enables merchants to accept payments seamlessly within their Android applications. Built with modern Android components (Kotlin, Activities, ViewModel, LiveData, and Material 3), it provides a clean, secure, and customizable payment experience.

Key Features

• Multiple Payment Methods: Credit/Debit Cards; Apple Pay routes are modeled in API but not available on Android devices
• 3D Secure Support: Built‑in 3DS authentication flow
• Saved Cards: Tokenization and saved card payments (when enabled by order)
• Modern UI: Material components with light/dark themes
• Internationalization: Multi‑language support (English, Arabic)
• Security: Token‑based authentication and secure network stack
• Accessibility: Compatible with Android accessibility features

Requirements

• Android minSdk 21+
• Target/Compile SDK 34
• Kotlin 1.9+
• Gradle Android Plugin 8+
• Your backend must return two URLs taken directly from the createOrder API response:
  • tokenUrl — value of _links.auth.href
  • orderUrl — value of _links.self.href

Installation

Gradle (Recommended)

Add the dependency from Maven Central (group and artifact):

// In your app module build.gradle.kts
dependencies {
    implementation("com.telr.android:payment-sdk:0.0.12")
}

If using Groovy:

dependencies {
    implementation 'com.telr.android:payment-sdk:0.0.12'
}

Ensure Maven Central is in your repositories (usually already present):

repositories {
    mavenCentral()
}

Manifest and Permissions

The SDK requires network permissions. If your app doesn’t already declare them, add to your app AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The SDK internally defines required activities. No additional <activity> entries are required in your app manifest.

Quick Start

Basic Implementation

Initialize the SDK once from a ComponentActivity, then launch the payment flow with your token and order URLs.

import androidx.activity.ComponentActivity
import com.telr.android.payment.sdk.Core
import com.telr.android.payment.sdk.data.sdk.PaymentRequest
import com.telr.android.payment.sdk.data.sdk.PaymentStatus

class CheckoutActivity : ComponentActivity() {
    override fun onStart() {
        super.onStart()
        val initResult = Core.getInstance().init(this)
        // Optionally handle initResult.sdkError
    }

    private fun startPayment(tokenUrl: String, orderUrl: String) {
        Core.getInstance().launchPaymentActivity(
            this,
            PaymentRequest(
                tokenUrl = tokenUrl,
                orderUrl = orderUrl
            )
        ) { result ->
            when (result.paymentStatus) {
                PaymentStatus.SUCCESS -> handleSuccess()
                PaymentStatus.FAILURE -> handleFailure(result.sdkError?.description)
                PaymentStatus.CANCELLED -> handleCancelled(result.sdkError?.code)
            }
        }
    }
}

Sample Flow

• Your backend creates an order and returns tokenUrl and orderUrl to your app.
• Call Core.init(activity) once.
• Call Core.launchPaymentActivity(...) with PaymentRequest(tokenUrl, orderUrl).
• Receive SDKResult in the callback on completion/cancel/failure.

Configuration

The Android SDK is intentionally minimal in required configuration. It automatically sets up networking and user‑agent headers. You should:

• Call Core.getInstance().init(activity) from a ComponentActivity prior to launching any payment UI.
• Provide valid server endpoints for tokenUrl and orderUrl.

Build variants expose a BuildConfig.DEBUG_MODE flag for internal logging behavior. For custom logging, hook into the result callback and your app’s own logger.

Payment Methods

Supported Payment Methods

Payment method availability is determined by the order returned from your backend:

• Credit/Debit Cards

  • Visa, Mastercard, American Express (and others where enabled)
  • 3D Secure authentication
  • Saved card payments (tokenized)

• Apple Pay

  • Represented in API models but not available to initiate natively on Android devices.

3D Secure Authentication

• Automatic 3DS challenge handling via an internal activity.
• Seamless return to your app with SDKResult.

Error Handling

SDK Result

Results are delivered via the callback from launchPaymentActivity:

import com.telr.android.payment.sdk.data.sdk.SDKResult
import com.telr.android.payment.sdk.data.sdk.PaymentStatus

// SDKResult(paymentStatus: PaymentStatus, sdkError: SDKError?)

• PaymentStatus.SUCCESS
• PaymentStatus.FAILURE
• PaymentStatus.CANCELLED

SDK Errors

Common error codes returned in SDKResult.sdkError:

• E001: Context must be a ComponentActivity
• E002: Unable to register for Activity Result (init must run on app load)
• E003: SDK not initialised (call Core.init() first)
• E004: Unable to fetch result from Payment Intent
• E005: Missing/invalid auth/order parameters
• E006: Authentication failed/expired
• E007: Fetch order failed (invalid order or node)
• E008: Make payment API failed or session expired
• E009: Unable to get 3DS validation status
• E010: Unable to get 3DS URL

Handle errors by showing user‑friendly messages and optionally retrying where appropriate.

Internationalization

• The SDK UI strings include English; Arabic is supported for RTL layout alignment when configured by your app’s locale.
• The SDK follows the host app locale and supports RTL mirroring.

Troubleshooting

Common Issues

1. Core.init() returns FAILED

   • Ensure you pass a ComponentActivity instance
   • Call init before launching payment

2. Network or Timeout errors

   • Verify tokenUrl and orderUrl
   • Check device connectivity and SSL configuration

3. Payment not processing

   • Confirm your backend endpoints return valid token/order responses
   • Ensure the order links include allowed operations and methods

4. 3DS challenge not returning

   • Check if the device can reach the ACS URL
   • Verify threeDs links in the order are valid

Debugging Tips

• Log the SDKResult and sdkError for diagnostics.
• Use your app’s network logger or proxy to inspect traffic to your backend.

API Reference

Core

object Core {
    fun getInstance(): Core
    fun init(context: Context): SDKInitResult // context must be a ComponentActivity
    fun launchPaymentActivity(
        context: Context,
        paymentRequest: PaymentRequest,
        callback: (SDKResult) -> Unit
    )
}

PaymentRequest

@Parcelize
data class PaymentRequest(
    val tokenUrl: String,
    val orderUrl: String
) : Parcelable

SDKInitResult

enum class InitStatus { SUCCESS, FAILED }

data class SDKInitResult(
    val initStatus: InitStatus,
    val sdkError: SDKError? = null
)

SDKResult

@Parcelize
data class SDKResult(
    val paymentStatus: PaymentStatus,
    val sdkError: SDKError?
) : Parcelable

PaymentStatus

enum class PaymentStatus { SUCCESS, FAILURE, CANCELLED }

Order and Amount (server response models)

data class Amount(val value: Double, val currency: String)

enum class OrderStatus { PENDING, AUTHORISED, PAID, CANCELLED, DECLINED }

Additional models include allowed payment methods, links, and 3DS details.