Ana içeriğe geç

BEX Full SDK — Entegrasyon Kılavuzu

Bu doküman, Android uygulamanıza BEX Full SDK’nın entegrasyonu için hazırlanmıştır.

Gereksinimler​

  • Min SDK: 24 (Android 7.0)
  • Compile SDK: 36+
  • Java / JVM target: 11
  • Kotlin: 1.9+

Hızlı Başlangıç​

val initParams = SdkInitParams(
    token = "your_initial_token",
    merchantId = "MERCHANT_123",
    transactionId = "TX_123",
    gsmNo = "5551234567",
    merchantUserId = "user_456",
    paymentInfo = SdkPaymentInfo(
        amount = 100.0,
        orderId = "ORDER_123",
        transactionDate = "2026-04-01T12:00:00Z",
        paymentSecurity = PaymentSecurity.TDS,
        currency = "TRY",
        installmentCount = 1
    ),
    environment = BexEnvironment.DEV
)

BexFullSdk.init(context, initParams, callback)
BexFullSdk.start()

Otomatik işlemler:

  1. SDK, başlangıç token’ınızı oturum token’ı ile değiştirir.
  2. Kullanıcı cüzdan durumunu kontrol eder (bağlı / bağlı değil / yeni kullanıcı).
  3. Kayıtlı kart varsa listeler.
  4. Uygun ödeme akışını gösterir.

Kurulum​

SDK Bağımlılığının Eklenmesi​

Seçenek 1: Modül bağımlılığı (geliştirme ve test için)

// settings.gradle.kts
include(":sdk")

// app/build.gradle.kts
dependencies {
    implementation(project(":sdk"))
}

Seçenek 2: AAR bağımlılığı (yayınlandığında)

// app/build.gradle.kts
dependencies {
    implementation("com.bkm.mobil:payment-sdk:1.0.0")
}

İzinler​

SDK internet erişimi gerektirmektedir. AndroidManifest.xml dosyanıza eklenmelidir:


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

    <application
    ...>
    <!-- aktiviteleriniz -->
</application></manifest>

Temel Entegrasyon​

Adım 1: SDK sınıflarının import edilmesi​

import com.bkm.mobil.sdk.api.BexFullSdk
import com.bkm.mobil.sdk.api.BexEnvironment
import com.bkm.mobil.sdk.api.PaymentCallback
import com.bkm.mobil.sdk.api.PaymentResult
import com.bkm.mobil.sdk.api.BexSdkError
import com.bkm.mobil.sdk.api.PaymentSecurity
import com.bkm.mobil.sdk.api.SdkPaymentInfo

Adım 2: SDK başlatma​

SDK, kimlik doğrulama token’ı, satıcı bilgileri ve sonuç geri çağrısı ile başlatılmalıdır:

BexFullSdk.init(
    context = this,
    initParams = SdkInitParams(
        token = "your_initial_auth_token",
        merchantId = "your_merchant_id",
        transactionId = "your_transaction_id",
        gsmNo = "5551234567",
        merchantUserId = "your_user_id",
        paymentInfo = SdkPaymentInfo(
            amount = 100.0,
            orderId = "your_order_id",
            transactionDate = "2026-04-01T12:00:00Z",
            paymentSecurity = PaymentSecurity.TDS,
            currency = "TRY",
            installmentCount = 1
        ),
        environment = BexEnvironment.DEV
    ),
    callback = object : PaymentCallback {
        override fun onPaymentSuccess(result: PaymentResult) {
            val transactionId = result.transactionId
            val amount = result.amount
            Log.d("Payment", "Başarılı. İşlem ID: $transactionId")
        }

        override fun onError(error: BexSdkError) {
            when (error) {
                is BexSdkError.Network -> {
                    Log.e("Payment", "Ağ hatası: ${error.message}")
                }
                is BexSdkError.Cancelled -> {
                    Log.d("Payment", "Ödeme iptal edildi")
                }
                is BexSdkError.Unauthorized -> {
                    Log.e("Payment", "Yetkisiz: ${error.message}")
                }
                is BexSdkError.Api -> {
                    Log.e("Payment", "API hatası: ${error.message}")
                }
                is BexSdkError.Unknown -> {
                    Log.e("Payment", "Hata: ${error.message}")
                }
            }
        }
    },
    theme = null
)

Adım 3: Ödeme akışını başlatma​

Seçenek 1: Tam ekran Activity (varsayılan)

BexFullSdk.start()

Seçenek 2: Alt sayfa (Bottom Sheet)

BexFullSdk.showAsBottomSheet(activity = this)

showAsBottomSheet, Activity türüne göre uyumlu çalışır; Activity, AppCompatActivity, ComponentActivity ve FragmentActivity desteklenir.

Örnek Kullanım​

Activity örneği​

class CheckoutActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            MaterialTheme {
                CheckoutScreen(
                    onPaymentClick = { startPayment() }
                )
            }
        }
    }

    private fun startPayment() {
        val token = getAuthToken()
        val merchantId = getMerchantId()
        val merchantUserId = getUserId()

        BexFullSdk.init(
            context = this,
            initParams = SdkInitParams(
                token = token,
                merchantId = merchantId,
                transactionId = "TX_123",
                gsmNo = "5551234567",
                merchantUserId = merchantUserId,
                paymentInfo = SdkPaymentInfo(
                    amount = 100.0,
                    orderId = "ORDER_123",
                    transactionDate = "2026-04-01T12:00:00Z",
                    paymentSecurity = PaymentSecurity.TDS,
                    currency = "TRY",
                    installmentCount = 1
                ),
                environment = BexEnvironment.DEV
            ),
            callback = object : PaymentCallback {
                override fun onPaymentSuccess(result: PaymentResult) {
                    Toast.makeText(
                        this@CheckoutActivity,
                        "Ödeme başarılı. TX: ${result.transactionId}",
                        Toast.LENGTH_LONG
                    ).show()
                    navigateToOrderConfirmation(result.transactionId)
                }

                override fun onError(error: BexSdkError) {
                    val message = when (error) {
                        is BexSdkError.Network -> "Ağ hatası. Tekrar denenmelidir."
                        is BexSdkError.Cancelled -> "Ödeme iptal edildi."
                        is BexSdkError.Api -> error.displayMessage
                        is BexSdkError.Unknown -> "Bir hata oluştu. Tekrar denenmelidir."
                        else -> error.displayMessage
                    }
                    Toast.makeText(this@CheckoutActivity, message, Toast.LENGTH_SHORT).show()
                }
            }
        )

        BexFullSdk.start()
    }

    private fun getAuthToken(): String {
        return "your_auth_token"
    }
}

Compose UI örneği​

@Composable
fun CheckoutScreen(onPaymentClick: () -> Unit) {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(24.dp),
        verticalArrangement = Arrangement.Center
    ) {
        Button(
            onClick = onPaymentClick,
            modifier = Modifier.fillMaxWidth()
        ) {
            Text("Öde")
        }
    }
}

API Referansı​

BexFullSdk​

Başlatma ve ödeme akışı için ana SDK nesnesidir.

init()​

Kullanımdan önce SDK’yı başlatır.

BexFullSdk.init(
    context: Context,
    initParams: SdkInitParams,
    callback: PaymentCallback,
    theme: BexFullSdkTheme? = null,
    config: BexFullSdkConfig = BexFullSdkConfig()
)

Parametreler:

  • context: Uygulama veya Activity context (uygulama context olarak saklanır).
  • initParams: Token, GSM numarası (gsmNo), ödeme tutarı vb. başlatma parametreleri.
  • callback: Ödeme sonucu (başarı / hata) için geri çağrı; CARD_SELECTION_ONLY modunda ayrıca onCardSelected kullanılır (aşağıdaki SdkMode bölümüne bakılmalıdır).
  • theme (isteğe bağlı): Uygulama görünümünüze uyum için özel tema.
  • config (isteğe bağlı): BexFullSdkConfig — Troy Sonic sesi (troySonicSoundEnabled) ve çalışma modu (mode / SdkMode). Ayrıntılar için BexFullSdkConfig bölümüne bakılmalıdır.

start()​

Ödeme ekranını tam ekran açar.

BexFullSdk.start()

Önce init() çağrılmamışsa IllegalStateException fırlatılır.

showAsBottomSheet()​

Ödeme ekranını alt sayfa (bottom sheet) olarak açar.

BexFullSdk.showAsBottomSheet(activity: Activity)

Tüm Activity türleriyle uyumludur. Modal alt sayfa, kaydırarak veya geri tuşu ile kapatıldığında iptal geri çağrısı tetiklenir.

BexFullSdkConfig​

init() çağrısında SDK davranışını (ses ve çalışma modu) özelleştirmek için kullanılır.

data class BexFullSdkConfig(
    val troySonicSoundEnabled: Boolean = true,
    val mode: SdkMode = SdkMode.PAYMENT
)
  • troySonicSoundEnabled: Troy Sonic ile ilişkili ses geri bildirimlerinin açık (true) veya kapalı (false) olması. Varsayılan: true.
  • mode: SDK’nın ödeme mi yoksa yalnızca kart seçimi mi yapacağını belirler. Ayrıntılar için SdkMode.

Örnek — kart seçim modu:

import com.bkm.mobil.sdk.api.BexFullSdkConfig
import com.bkm.mobil.sdk.api.SdkMode

BexFullSdk.init(
    context = this,
    initParams = initParams,
    callback = callback,
    theme = null,
    config = BexFullSdkConfig(
        troySonicSoundEnabled = true,
        mode = SdkMode.CARD_SELECTION_ONLY
    )
)

SdkMode​

SDK’nın kart listesi ekranındaki birincil aksiyonu ve ödeme başlatılıp başlatılmayacağını belirler.

enum class SdkMode {
    PAYMENT,
    CARD_SELECTION_ONLY
}

PAYMENT (varsayılan)​

Standart ödeme akışı: kullanıcı kartı seçer, SDK ödeme işlemini (3DS, OTP vb. paymentSecurity değerine göre) başlatır ve tamamlandığında onPaymentSuccess(PaymentResult) çağrılır. Kart seçim ekranındaki birincil buton tutar ve para birimini gösterir (ör. «… Öde»). SdkInitParams.paymentInfo dolu olmalıdır; aksi halde ödeme başlatılamaz ve kullanıcı aksiyonu sırasında BexSdkError.Unknown("Ödeme bilgisi eksik. [PAYMENT_MODE_PAYMENT_INFO_NULL]") hatası alınır.

CARD_SELECTION_ONLY​

Yalnızca kart seçimi: kullanıcı kayıtlı kartlardan birini seçer; SDK ödeme başlatmaz. Sonuç PaymentCallback.onCardSelected(CardSelectionResult) ile döner; CardSelectionResult.selectedCard içinde seçilen kartın BexCardInfo bilgisi yer alır. Birincil buton metni tutar göstermez; «Kartı Seç» benzeri bir ifade kullanılır. Entegrasyonda bu mod için onCardSelected metodunun override edilmesi gerekmektedir (arayüzde varsayılan implementasyon boştur, geriye dönük uyumluluk içindir).

Not: CARD_SELECTION_ONLY kullanırken ödeme API’leri çağrılmadığı için paymentInfo zorunlu değildir; yine de initParams (token, merchantId, transactionId, gsmNo, merchantUserId vb.) cüzdan ve kart listesi için gerektiği gibi sağlanmalıdır.

SdkInitParams​

SDK başlatma parametreleri.

data class SdkInitParams(
    val token: String,            // Backend'den alınan başlangıç token'ı
    val merchantId: String,       // Satıcı tanımlayıcı
    val transactionId: String,    // Satıcı tarafındaki işlem/transaction tanımlayıcı
    val gsmNo: String,           // Kullanıcı GSM numarası (5XXXXXXXXX)
    val merchantUserId: String,   // Satıcı tarafındaki kullanıcı tanımlayıcı
    val paymentInfo: SdkPaymentInfo? = null,
    val environment: BexEnvironment = BexEnvironment.DEV
)

Token akışı: SDK iki aşamalı token kullanır. Sizin verdiğiniz başlangıç token’ı ile /sdk/init çağrılır; backend oturum token’ı döner ve SDK bunu güvenli saklar. Sonraki tüm API çağrıları otomatik olarak bu oturum token’ı ile yapılır.

SdkPaymentInfo​

İşlem başlatma sırasında kullanılabilen ödeme bilgileri.

data class SdkPaymentInfo(
    val amount: Double,
    val orderId: String,
    val transactionDate: String,
    val paymentSecurity: PaymentSecurity,
    val currency: String,
    val installmentCount: Int
)
  • paymentSecurity: İşlemin 3DS (TDS) veya Non-3D + OTP isteği (OTP / NONE) ile başlatılmasını belirtir. Bu yalnızca istemci tarafı bir tercihtir; OTP dönüşü her zaman yanıt gövdesine göre ele alınmalıdır. Non-3D isteklerde API gövdesine withOtp alanı eklenir (OTP → true, NONE → false).

PaymentSecurity​

enum class PaymentSecurity {
    TDS,
    OTP,
    NONE
}
  • TDS: 3-D Secure; 3D init uçları kullanılır.
  • OTP: Non-3D init, istek gövdesinde withOtp = true.
  • NONE: Non-3D init, istek gövdesinde withOtp = false.

BexEnvironment​

SDK’nın bağlanacağı API ortamını belirler.

enum class BexEnvironment { DEV, TEST, PREPROD, PROD }

PaymentCallback​

Ödeme sonuçlarını almak için arayüz.

interface PaymentCallback {
    fun onPaymentSuccess(result: PaymentResult)
    fun onError(error: BexSdkError)
    fun onCardSelected(result: CardSelectionResult) { }
}
  • onPaymentSuccess(result: PaymentResult): Ödeme başarıyla tamamlandığında çağrılır (SdkMode.PAYMENT).
  • onError(error: BexSdkError): Ödeme başarısız veya iptal edildiğinde çağrılır.
  • onCardSelected(result: CardSelectionResult): Yalnızca SdkMode.CARD_SELECTION_ONLY modunda, kullanıcı kartı seçtiğinde çağrılır. Varsayılan gövde boştur; bu modu kullanırken seçilen kart burada işlenmelidir. Yapı için CardSelectionResult bölümüne bakılmalıdır.

PaymentResult​

Başarılı ödeme sonucu.

data class PaymentResult(
    val transactionId: String,
    val amount: Double,
    val cardNumber: String?
)

SdkMode.CARD_SELECTION_ONLY modunda ödeme yapılmadığı için onPaymentSuccess bu akışta tetiklenmez; bunun yerine onCardSelected kullanılır.

CardSelectionResult​

Yalnızca kart seçim modunda (SdkMode.CARD_SELECTION_ONLY) onCardSelected ile dönen sonuç.

data class CardSelectionResult(
    val selectedCard: BexCardInfo
)

BexCardInfo​

Kart seçim modu yanıtında CardSelectionResult.selectedCard alanı içinde dönen kart bilgisi.

Dönen alanlar:

  • cardId: Kartın benzersiz kimliği
  • maskCardNumber: Maskelenmiş kart numarası
  • cardAlias: Kartın takma adı
  • binValue: Kart BIN değeri
  • imageUrl: Kart görseli URL’i
  • bankInformation: Banka/kart bilgileri
    • cardType: Kart tipi (ör. CreditCard)
    • cardBrandType: Kart marka tipi
    • cardBrand: Kart markası (ör. Troy)
    • bankShortName: Banka kısa adı (ör. TESTBANK)
  • active: Kartın aktiflik durumu

Yanıt örneği:

{
  "cardId": "019d2dad-34bc-7b00-959d-0bef3009afa5",
  "maskCardNumber": "123456******1234",
  "cardAlias": "Maaş Kartım",
  "binValue": "12345678",
  "imageUrl": "https://...default_card.png",
  "bankInformation": {
    "cardType": "CreditCard",
    "cardBrandType": "Marka Yok",
    "cardBrand": "Troy",
    "bankShortName": "TESTBANK"
  },
  "active": true
}

BexSdkError​

Hata türleri (mühürlü sınıf).

sealed class BexSdkError {
    data class Network(val message: String) : BexSdkError()
    data class Cancelled(val message: String) : BexSdkError()
    data class Unauthorized(val message: String) : BexSdkError()
    data class Unknown(val message: String) : BexSdkError()
    data class Api(val message: String, val title: String? = null, val code: Int? = null) :
        BexSdkError()
}
  • Network: Ağ veya API iletişim hatası.
  • Cancelled: Kullanıcı ödemeyi iptal etti.
  • Unauthorized: Token geçersiz veya süresi dolmuş.
  • Unknown: Beklenmeyen hata.
  • Api: Sunucudan dönen iş kuralı hatası; displayMessage kullanıcıya gösterilebilir.

Sunum Modları​

1. Tam ekran Activity (varsayılan)​

BexFullSdk.init(context, initParams, callback)
BexFullSdk.start()

2. Alt sayfa (Bottom Sheet)​

BexFullSdk.init(context, initParams, callback)
BexFullSdk.showAsBottomSheet(this)

Alt sayfa modu: yuvarlatılmış üst köşe, sürükleyerek kapatma, geri tuşu ile iptal. Tam ekran modu ile aynı işlevsellik ve geri çağrılar kullanılır.

Tema Özelleştirme​

SDK renk, tipografi, boşluk ve şekil özelleştirmesini destekler. Tüm alanlar isteğe bağlıdır; verilmezse varsayılan değerler kullanılır.

Temel kullanım​

Tema API’si hem XML hem Compose uygulamalarla uyumludur; Compose import’u zorunlu değildir.

Compose örneği:

import com.bkm.mobil.sdk.api.BexFullSdkTheme
import androidx.compose.ui.graphics.toArgb

val customTheme = BexFullSdkTheme(
    colors = BexFullSdkTheme.Colors(
        primary = androidx.compose.ui.graphics.Color(0xFF6200EE).toArgb(),
        textPrimary = 0xFF000000
    ),
    shape = BexFullSdkTheme.Shape(
        buttonCornerRadius = 8f
    )
)

BexFullSdk.init(
    context = this,
    initParams = initParams,
    callback = callback,
    theme = customTheme
)

XML örneği (Compose olmadan):

import com.bkm.mobil.sdk.api.BexFullSdkTheme

val customTheme = BexFullSdkTheme(
    colors = BexFullSdkTheme.Colors(
        primary = getColor(R.color.brand_primary),
        buttonPrimary = getColor(R.color.brand_primary),
        textPrimary = getColor(R.color.text_primary)
    ),
    shape = BexFullSdkTheme.Shape(
        buttonCornerRadius = BexFullSdkTheme.DP_8,
        buttonBorderWidth = BexFullSdkTheme.DP_2
    )
)

Renk formatı​

Android renk tamsayıları (0xAARRGGBB) kullanılır. Örn: 0xFF6200EE, getColor(R.color.xxx), Compose’da Color(...).toArgb().

Kısmi özelleştirme​

Yalnızca değiştirmek istediğiniz alanlar verilmelidir; diğerleri SDK varsayılanı kalır.

Sorun Giderme​

“SDK başlatılmadı” hatası: start() veya showAsBottomSheet() öncesinde mutlaka init() çağrılmalıdır.

Ağ hataları: Manifest’te internet izni, cihaz bağlantısı ve token geçerliliği kontrol edilmelidir.

Derleme hataları: SDK bağımlılığının eklendiğinden ve Gradle senkronizasyonunun yapıldığından emin olunmalıdır.

Ödeme ekranı açılmıyor: Logcat’te hata mesajları kontrol edilmelidir; init() çağrıldığından ve context ile token’ın geçerli olduğundan emin olunmalıdır.

Ödeme bilgisi eksik: SdkMode.PAYMENT kullanılırken SdkInitParams.paymentInfo boş bırakılmamalıdır; aksi halde kullanıcı aksiyonu sırasında Ödeme bilgisi eksik. [PAYMENT_MODE_PAYMENT_INFO_NULL] hatası alınır.