Android SDK

The Android SDK supports two modes:

Native checkout — full in-app payment UI (Jetpack Compose), no browser redirect
Hosted checkout — create a session server-side, open the URL in a browser

Requirements

Android Studio
Kotlin 1.9+
minSdk 23 (Android 6.0+)
Jetpack Compose (for native checkout)

Install

JitPack (recommended)

Add JitPack to your project settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

Add the dependency in your module build.gradle.kts:

dependencies {
    implementation("com.github.OrcusHQ:orcuspay-android:1.1.0")
}

Git submodule

git submodule add https://github.com/OrcusHQ/orcuspay-android.git vendor/orcuspay-android

Then include the module in settings.gradle.kts:

include(":orcuspay")
project(":orcuspay").projectDir = file("vendor/orcuspay-android/orcuspay")

dependencies {
    implementation(project(":orcuspay"))
}

Native Checkout

Native checkout handles the entire payment flow inside your app — no browser redirect. The SDK shows a bottom-sheet UI with payment method selection, transaction verification, and gateway checkout.

1. Create a session (server-side)

Create a checkout session from your backend and pass only the session ID to your Android app. Never ship secret keys in a public mobile app.

Node.js

const session = await orcus.createCheckoutSession({
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  line_items: [
    {
      quantity: 1,
      price_data: {
        unit_amount: 50000,
        product_data: { name: 'Premium Plan' },
      },
    },
  ],
})

// Send session.id to your Android app

2. Register for result

Register an activity result launcher before starting the checkout. This must be called in onCreate or at class init time — not inside a click handler.

import com.orcuspay.android.checkout.OrcusCheckout
import com.orcuspay.android.checkout.OrcusCheckoutResult

class PaymentActivity : ComponentActivity() {

    private val checkoutLauncher = OrcusCheckout.registerForResult(this) { result ->
        when (result) {
            is OrcusCheckoutResult.Completed -> {
                // Payment succeeded
                // result.sessionId has the payment ID
                showSuccess()
            }
            is OrcusCheckoutResult.Failed -> {
                // Payment failed
                // result.error has the message
                showError(result.error)
            }
            is OrcusCheckoutResult.Canceled -> {
                // User dismissed the checkout
            }
        }
    }
}

3. Open checkout

Call OrcusCheckout.open() with the session ID you received from your backend:

fun startPayment(sessionId: String) {
    OrcusCheckout.open(
        launcher = checkoutLauncher,
        activity = this,
        sessionId = sessionId,
    )
}

What the user sees

The checkout screen shows a bottom sheet with these steps:

Payment method selection — all available methods with icons, business branding, and the total amount
Depending on the selected method:
- bKash / Nagad / Rocket — a native form to enter the Transaction ID after sending money
- Stripe — an embedded card/Google Pay checkout form
- SSLCommerz — the SSLCommerz gateway for local bank and card payments

Custom API URL

For self-hosted Orcuspay instances, pass your API URL:

OrcusCheckout.open(
    launcher = checkoutLauncher,
    activity = this,
    sessionId = sessionId,
    apiUrl = "https://your-instance.com/api",
)

Hosted Checkout

For the redirect-based flow, create a session on your backend and open the checkout URL in Chrome Custom Tabs.

Do not ship production secret keys inside a public mobile app. The hosted checkout client shown below is for internal/trusted apps only. For consumer-facing apps, create sessions from your backend and use native checkout.

import com.orcuspay.android.OrcusPayClient
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import kotlinx.serialization.json.putJsonArray
import kotlinx.serialization.json.putJsonObject
import kotlinx.serialization.json.addJsonObject

val client = OrcusPayClient(
    accessKey = "ak_test_xxxxx",
    secretKey = "sk_test_xxxxx",
)

val payload = buildJsonObject {
    putJsonObject("customer") {
        put("name", "Test Customer")
        put("email", "test@example.com")
        put("phone", "01700000000")
    }
    put("success_url", "https://example.com/success")
    put("cancel_url", "https://example.com/cancel")
    putJsonArray("line_items") {
        addJsonObject {
            put("quantity", 1)
            putJsonObject("price_data") {
                put("unit_amount", 10000)
                putJsonObject("product_data") {
                    put("name", "Demo product")
                }
            }
        }
    }
}

val session = client.createCheckoutSession(payload)
val checkoutUrl = session["url"].toString().trim('"')
// Open checkoutUrl in Chrome Custom Tabs

Documentation

Quickstart

SDKs

Guides

Requirements

Install

JitPack (recommended)

Git submodule

Native Checkout

1. Create a session (server-side)

2. Register for result

3. Open checkout

What the user sees

Custom API URL

Hosted Checkout

​Requirements

​Install

​JitPack (recommended)

​Git submodule

​Native Checkout

​1. Create a session (server-side)

​2. Register for result

​3. Open checkout

​What the user sees

​Custom API URL

​Hosted Checkout

Requirements

Install

JitPack (recommended)

Git submodule

Native Checkout

1. Create a session (server-side)

2. Register for result

3. Open checkout

What the user sees

Custom API URL

Hosted Checkout