Android SDK

com.qasimha:checkout-android opens a Qasimha hosted checkout from your Android app and reports how it ended. Your server creates the session and hands the app a paymentUrl; the SDK opens it in a Custom Tab (default) or a hardened WebView, watches for the return to your app and gives you a typed result. It holds no secret key, stores nothing and tracks nothing.

Requirements

Install

dependencies {
    implementation("com.qasimha:checkout-android:0.1.0")
}

Add the return-scheme manifest placeholder to your app module. The library manifest needs it to build, even if you only use App Links:

android {
    defaultConfig {
        manifestPlaceholders["qasimhaReturnScheme"] = "myshop"
    }
}

If you only use App Links, set it to something unique, for example your application id.

Set up the return into your app

Only Presentation.CUSTOM_TAB needs this: the browser has to bring the shopper back into your app. In WEB_VIEW mode the SDK intercepts the return URLs inside the WebView, so no manifest work is needed.

<activity android:name="com.qasimha.checkout.QasimhaReturnActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="shop.example" android:pathPrefix="/qasimha/return" />
    </intent-filter>
</activity>

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    val data = intent.data ?: return
    if (!QasimhaCheckout.handleReturn(data)) handleMyOwnDeepLink(data)
}

manifestPlaceholders["qasimhaReturnScheme"] = "myshop"

MerchantUrl(
    success = "myshop://qasimha/return",
    failure = "myshop://qasimha/return",
    cancel = "myshop://qasimha/cancel",
)

Start a checkout

Get paymentUrl from your server, then launch the checkout with the same three return URLs your server sent when creating the session. Use the Activity Result contract: it survives process death.

class CheckoutActivity : AppCompatActivity() {
    private val checkout = registerForActivityResult(QasimhaCheckoutContract()) { result ->
        when (result) {
            is CheckoutResult.Success -> confirmWithMyServer(result.orderId)
            is CheckoutResult.Failure -> showFailure(result.status)
            CheckoutResult.Cancelled -> showCart()
        }
    }

    fun pay(paymentUrl: String) {
        checkout.launch(
            CheckoutOptions(
                paymentUrl = paymentUrl,
                merchantUrl = MerchantUrl(
                    success = "https://shop.example/qasimha/return?order=1001",
                    failure = "https://shop.example/qasimha/return?order=1001",
                    cancel = "https://shop.example/cart",
                ),
                presentation = Presentation.CUSTOM_TAB,
                language = "ar",
            ),
        )
    }
}

A callback API also exists: QasimhaCheckout.start(activity, options) { result -> ... } (from Java: QasimhaCheckout.start(this, options, result -> { ...; return Unit.INSTANCE; })). The callback lives in memory: if Android kills the process while the checkout is open, it is lost. Prefer the contract.

CheckoutOptions

An invalid value throws IllegalArgumentException from the constructor.

Handle the result and confirm on your server

Do not show "paid" on any result. On Success, send orderId to your server. Your server calls GET /api/v1/merchant/orders/{orderId} (orders.get in the server SDKs) with its secret key and fulfils only if the order is paid. Your server also receives the webhook for the same order.

If the process was killed while the Custom Tab was open, there is no pending checkout. The App Link then arrives at your activity as a normal deep link with orderId, orderReferenceId and status in the query, and your server can still confirm the order.

Custom Tab or WebView

• CUSTOM_TAB (default). The system browser sheet. The shopper gets the platform's TLS, autofill and cookie isolation, and the journey's third-party pages (payment provider, Nafath app switch, App Links into the Qasimha app) work as in a browser. Use this unless you have a reason not to.
• WEB_VIEW (opt-in). QasimhaCheckoutActivity hosts a hardened WebView: no file or content access, no mixed content, no addJavascriptInterface, Safe Browsing on, third-party cookies off, permission prompts denied. Only https hosts on the allow-list load (the paymentUrl host, your return hosts and webViewAllowedHosts); everything else, including intent:// and app-switch schemes, is dropped. A Nafath app hand-off does not work here; the Nafath web flow does when its host is allow-listed. A TLS error ends with Failure("ssl_error").

Promo view

QasimhaPromoView shows "Split into 4 monthly payments of [riyal symbol] 300" on product and cart screens. It uses your publishable key only.

<com.qasimha.checkout.QasimhaPromoView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:qasimhaPublicKey="pk_test_..."
    app:qasimhaAmount="1200"
    app:qasimhaLang="ar" />

promo.publicKey = "pk_test_..."
promo.amount = "300.50"
promo.lang = "en"
promo.textView.textSize = 16f
promo.refresh()

• Calls GET /api/v1/widget/plans with the X-Public-Key header. pk_test_ keys go to UAT, pk_live_ keys to production.
• Fails closed: the view is GONE when the key or amount is invalid, the request fails, or the amount is outside the plan range. It never invents a number.
• Nothing is cached; every attribute change re-fetches. Style it through textView, and call refresh() after changing the text size.

Release builds

• R8 / ProGuard: the AAR ships consumer-rules.pro. It keeps the public API (com.qasimha.checkout.* and the CheckoutResult subclasses) and lets R8 shrink and obfuscate the internals with your app. You do not need to add rules.
• The SDK uses no reflection. No mapping file or crash report leaves your app through the SDK.

Security

• No secret on the device. Keep sk_test_... / sk_live_... on your server. The app only ever sees paymentUrl and, for the promo view, a pk_ key.
• No storage, analytics, advertising id or fingerprinting. No certificate pinning; TLS validation is the platform's.
• WebView cookies: the WebView shares your app's WebView cookie jar, as any WebView does. The SDK does not read or persist it.
• PCI DSS: no card data passes through the SDK or your app. You stay in SAQ-A scope.
• App hardening: root detection, anti-tamper, anti-hooking and RASP are recommended for apps that take payments. The SDK does not perform them.

Troubleshooting

Related

• Mobile SDKs overview
• Return URLs
• Order lifecycle
• Webhooks