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:4.0.2")
}

If using Groovy:

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

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.

Add Card Flow

Use launchAddCardActivity when you want to verify and save a new card (without immediate checkout capture).

Merchant-side flow

Merchant backend creates a VERIFY order.
Merchant backend returns tokenUrl + orderUrl to the app.
App opens SDK add-card sheet with those URLs.
SDK handles card entry, 3DS, and completion callback.
On success callback, app stores the saved card details and payment reference for future use.

Example

import com.telr.android.payment.sdk.Core
import com.telr.android.payment.sdk.data.sdk.PaymentRequest
import com.telr.android.payment.sdk.data.sdk.SDKAddCardResult

val paymentRequest = PaymentRequest(
    tokenUrl = addCardTokenUrl,
    orderUrl = addCardOrderUrl
)

Core.getInstance().launchAddCardActivity(this, paymentRequest) { result ->
    when (result.paymentStatus) {
        PaymentStatus.SUCCESS -> {
            // result.ref — payment reference from the VERIFY transaction (store for saved-card payments)
            // result.maskedName — masked cardholder name (store for SDKSavedCardInput)
            // result.savedCards — list of saved card details (token, maskedCard, expiry, scheme)
            val cards = result.savedCards
            val paymentRef = result.ref
        }
        PaymentStatus.CANCELLED -> { /* user cancelled */ }
        PaymentStatus.PENDING -> { /* order status being confirmed */ }
        PaymentStatus.FAILURE -> {
            // result.message contains the error description
            // result.errorCode contains the SDK error code (nullable)
        }
    }
}

SDKAddCardResult

@Parcelize
data class SDKAddCardResult(
    val paymentStatus: PaymentStatus,
    val message: String,
    val errorCode: String? = null,
    val ref: String? = null,             // payment reference for CONT transactions
    val savedCards: List<SDKSavedCardInput>? = null,
    val maskedName: String? = null       // e.g. "J*** D**"
) : Parcelable

Pay with Saved Card Flow

UselaunchSavedCardPaymentActivitywhen a customer selects a saved card and CVV re-entry and/or 3DS is required (typically for higher-value transactions per your risk policy).

📘
For low-value or recurring transactions, your backend can process the saved card silently usingclass: CONTwith the payment reference from the add-card flow — no CVV or user interaction needed. UselaunchSavedCardPaymentActivity(ECOM) when your risk policy requires CVV re-entry or 3DS authentication.

Merchant-side flow

Merchant backend creates a SALE order.
Merchant backend returns tokenUrl + orderUrl to the app.
App opens the SDK saved-card sheet with those URLs and the saved card details.
SDK displays the masked card (read-only) and prompts for CVV only.
SDK handles payment, 3DS, and calls the completion callback.

Example

import com.telr.android.payment.sdk.Core
import com.telr.android.payment.sdk.data.sdk.SDKSavedCardInput
import com.telr.android.payment.sdk.data.sdk.SavedCardPaymentLaunchRequest
import com.telr.android.payment.sdk.data.sdk.PaymentStatus

val savedCard = SDKSavedCardInput(
    token = "card_token_here",
    maskedCard = "**** 1111",     // from add-card flow
    expiry = "12/30",
    scheme = "VISA",
    maskedName = "J*** D**"       // optional, shown on the sheet
)

val launchRequest = SavedCardPaymentLaunchRequest(
    tokenUrl = checkoutTokenUrl,
    orderUrl = checkoutOrderUrl,
    savedCard = savedCard
)

Core.getInstance().launchSavedCardPaymentActivity(this, launchRequest) { result ->
    when (result.paymentStatus) {
        PaymentStatus.SUCCESS -> handleSuccess()
        PaymentStatus.CANCELLED -> handleCancelled()
        else -> handleFailure(result.sdkError?.description)
    }
}

SDKSavedCardInput

@Parcelize
data class SDKSavedCardInput(
    val token: String,           // card token from add-card flow
    val maskedCard: String,      // e.g. "**** 1111"
    val expiry: String,          // e.g. "12/30"
    val scheme: String,          // e.g. "VISA"
    val maskedName: String? = null // optional, e.g. "J*** D**"
) : Parcelable

SavedCardPaymentLaunchRequest

@Parcelize
data class SavedCardPaymentLaunchRequest(
    val tokenUrl: String,
    val orderUrl: String,
    val savedCard: SDKSavedCardInput
) : Parcelable

Pay with Card Flow

UselaunchPayWithCardActivitywhen you want to collect card details and process an immediate payment (e.g., gift card purchases) without saving the card.

Merchant-side flow

Merchant backend creates a SALE order.
Merchant backend returns tokenUrl + orderUrl to the app.
App opens SDK pay-with-card sheet with those URLs.
SDK handles card entry, BIN lookup (including international card blocking), 3DS, and completion callback.
On success callback, the payment is complete.

Example

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

val paymentRequest = PaymentRequest(
    tokenUrl = checkoutTokenUrl,
    orderUrl = checkoutOrderUrl
)

Core.getInstance().launchPayWithCardActivity(this, paymentRequest) { result ->
    when (result.paymentStatus) {
        PaymentStatus.SUCCESS -> handleSuccess()
        PaymentStatus.CANCELLED -> handleCancelled()
        else -> handleFailure(result.sdkError?.description)
    }
}

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

Core.init() returns FAILED
- Ensure you pass a ComponentActivity instance
- Call init before launching payment
Network or Timeout errors
- Verify tokenUrl and orderUrl
- Check device connectivity and SSL configuration
Payment not processing
- Confirm your backend endpoints return valid token/order responses
- Ensure the order links include allowed operations and methods
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.