Bas Pay SDK — Native Android / Kotlin Integration Guide#
This document explains how to integrate bas_pay-release.aar and BankySDKManager-release.aar into a native Android (Kotlin) project — without Flutter.
Table of Contents#
Overview#
Bas Pay SDK provides a payment experience for Android applications. It consists of two AAR libraries:| File | Description |
|---|
bas_pay-release.aar | Core SDK — Contains BasPay class and basSdk Composable for initiating and handling payments |
BankySDKManager-release.aar | Supporting SDK — Banky banking infrastructure dependency required by the core SDK |
Architecture#
┌─────────────────────────────────────┐
│ Your Kotlin App │
│ │
│ BasPay.start(activity, params) │
│ or basSdk(params) │
└──────────────┬──────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ bas_pay-release.aar │
│ ┌──────────────────────────────┐ │
│ │ BasPay (Entry Point) │ │
│ │ • start() │ │
│ │ • getResult() │ │
│ │ • DEFAULT_REQUEST_CODE │ │
│ ├──────────────────────────────┤ │
│ │ basSdk() Composable │ │
│ │ (Jetpack Compose UI) │ │
│ └──────────────────────────────┘ │
└──────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ BankySDKManager-release.aar │
│ (Banking infrastructure layer) │
└──────────────────────────────────────┘
Requirements#
| Requirement | Minimum Version |
|---|
Android minSdk | 24 (Android 7.0) |
Android compileSdk | 36 |
| Kotlin | 2.1.0 |
| Java Compatibility | 11 |
| Jetpack Compose | Required (for Compose method) |
| AGP (Android Gradle Plugin) | 8.7.0+ |
Installation#
Step 1: Copy AAR Files#
Create a libs directory inside your app module and copy both AAR files:your-project/
├── app/
│ ├── libs/
│ │ ├── bas_pay-release.aar
│ │ └── BankySDKManager-release.aar
│ ├── src/
│ └── build.gradle.kts
├── build.gradle.kts
└── settings.gradle.kts
flatDir to your project-level repositories so Gradle can find local AAR files:If using the Compose method with a dedicated Activity, register it:
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application>
<activity android:name=".MainActivity" android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity
android:name=".BasPayActivity"
android:exported="false"
android:theme="@android:style/Theme.NoTitleBar" />
</application>
</manifest>
Important: The Theme.NoTitleBar theme is recommended for a clean payment UI experience.
Usage#
There are two methods to integrate Bas Pay:Method A: BasPay.start() — Activity Result Pattern (Recommended)#
This is the simplest approach. It launches the payment screen as an Activity and returns the result via onActivityResult.Method B: Jetpack Compose — basSdk() Composable#
Use this method if your app is built with Jetpack Compose. The basSdk() composable renders the full payment UI.Launching the Compose Activity from another screen:
Parameters Reference#
| Parameter | Type | Required | Default | Description |
|---|
trxToken | String | ✅ Yes | — | The transaction token obtained from your backend. This is the unique identifier for the payment session. |
userIdentifier | String? | ❌ No | null | User identifier (e.g., phone number like "733733733") |
fullName | String? | ❌ No | null | Full name of the paying user |
language | String? | ❌ No | "ar" | UI language: "ar" (Arabic) or "en" (English) |
platform | String? | ❌ No | "Native" | Platform identifier. Use "Native" for Kotlin apps |
product | String? | ❌ No | null | Product name or identifier |
environment | String? | ❌ No | "prod" | Environment: "prod" for production, "dev" for development/testing |
requestCode | Int | ✅ Yes (Method A) | BasPay.DEFAULT_REQUEST_CODE | Request code for onActivityResult. Always use BasPay.DEFAULT_REQUEST_CODE |
onReturnDataToIOS | Callback? | — | null | iOS only. Always pass null on Android |
Response Handling#
Response JSON Structure#
After the payment flow completes, BasPay.getResult(data) returns a JSON string with this structure:{
"status": true,
"message": "Payment completed successfully",
"result": { ... },
"code": 200
}
Response Fields#
| Field | Type | Description |
|---|
status | Boolean | true = payment succeeded, false = payment failed |
message | String | Human-readable status message |
result | Any? | Additional payment result data (structure varies) |
code | Int | Status code. 699 = unknown/default error code |
ResultModel Helper (Optional)#
You can create a helper data class to parse the response:
Environment Configuration#
| Environment | Value | Use Case |
|---|
| Production | "prod" | Live payments with real transactions |
| Development | "dev" | Testing and development — no real charges |
Error Handling#
Common error scenarios and how to handle them:| Scenario | How to Detect | Recommended Action |
|---|
| User cancelled payment | BasPay.getResult(data) returns null | Show "Payment cancelled" message |
| Payment failed | status == false in response | Show error message from message field |
| Invalid token | status == false, check code | Request a new token from your backend |
| Network error | status == false | Ask user to retry |
| Unknown error | code == 699 | Log error, show generic error message |
Full Example — Complete Activity#
Full Example — Jetpack Compose#
Troubleshooting#
| Problem | Solution |
|---|
ClassNotFoundException for BasPay | Ensure bas_pay-release.aar is in the libs/ folder and flatDir is configured |
Could not resolve BankySDKManager | Ensure BankySDKManager-release.aar is in libs/ or available via Maven |
Duplicate class errors | Check the exclude rules in the BankySDKManager dependency |
| Compose compilation errors | Ensure org.jetbrains.kotlin.plugin.compose plugin is applied |
minSdk errors | Set minSdk = 24 or higher |
onActivityResult not called | Ensure you're using BasPay.DEFAULT_REQUEST_CODE |
null result from getResult() | User likely cancelled the payment flow |
Files Checklist#
Before handing off to the Kotlin developer, ensure they have:
API Quick Reference#
Modified at 2026-05-12 20:54:59
