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ıç​

BEX Full SDK iki farklı entegrasyon yaklaşımıyla kullanılabilir:

  • Full SDK entegrasyon: SdkMode.PAYMENT (varsayılan) — SDK ödeme akışını uçtan uca yönetir.
  • Hibrit SDK entegrasyon: CARD_SELECTION_ONLY = true → SdkMode.CARD_SELECTION_ONLY — SDK yalnızca kart seçtirir, ödeme satıcı uygulamasında yürütülür.

1) Full SDK entegrasyon (SdkMode.PAYMENT)​

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,
        successUrl = "https://merchant.example.com/payment/callback/success",
        failUrl = "https://merchant.example.com/payment/callback/fail"
    ),
    environment = BexEnvironment.DEV
)

BexFullSdk.init(
    context = context,
    initParams = initParams,
    callback = callback,
    config = BexFullSdkConfig(mode = SdkMode.PAYMENT)
)
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.

2) Hibrit SDK entegrasyon (CARD_SELECTION_ONLY = true)​

Hibrit entegrasyonda CARD_SELECTION_ONLY = true ifadesi, SDK içindeki çalışma modu olan SdkMode.CARD_SELECTION_ONLY anlamına gelir. Bu modda SDK ödeme başlatmaz; yalnızca kart seçtirir ve seçilen kartı PaymentCallback.onCardSelected(...) ile döner.

val initParams = SdkInitParams(
    token = "your_initial_token",
    merchantId = "MERCHANT_123",
    transactionId = "TX_123",
    gsmNo = "5551234567",
    merchantUserId = "user_456",
    // paymentInfo bu modda zorunlu değildir
    environment = BexEnvironment.DEV
)

BexFullSdk.init(
    context = context,
    initParams = initParams,
    callback = callback,
    config = BexFullSdkConfig(mode = SdkMode.CARD_SELECTION_ONLY)
)

// Kart listesi ekranını açar (tam ekran veya bottom sheet)
BexFullSdk.start()

Kurulum​

1) Maven Repository'nin Eklenmesi​

BEX Full SDK, BKM özel Maven repository'de yayınlanmaktadır. İlk olarak projenin settings.gradle.kts dosyasına repository adresi eklenmelidir:

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // mevcut repository tanımlarınız (google(), mavenCentral() vb.)
        maven { url = uri("https://entegrasyon-repo.bkmexpress.com.tr/repository/bkm-mobil-sdk/") }
    }
}

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

Seçenek 1: Doğrudan bağımlılık (Kotlin DSL)

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

Seçenek 2: Version catalog (libs.versions.toml) ile

# gradle/libs.versions.toml
[versions]
fullSdk = "0.0.1"

[libraries]
full-sdk = { module = "com.bkm.mobil:full-sdk", version.ref = "fullSdk" }
// app/build.gradle.kts
dependencies {
    implementation(libs.full.sdk)
}

İ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​

SDK sınıflarının import edilmesi​

Bu bölümdeki import’lar Full + Hibrit entegrasyon için ortaktır. Hibrit mod için gereken ek import aşağıdadır.

import com.bkm.mobil.sdk.api.BexFullSdk
import com.bkm.mobil.sdk.api.BexEnvironment
import com.bkm.mobil.sdk.api.BexFullSdkConfig
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
import com.bkm.mobil.sdk.api.SdkMode

Hibrit mod için ek import:

import com.bkm.mobil.sdk.api.CardSelectionResult

Full SDK entegrasyon (SDK ödeme başlatır) — SdkMode.PAYMENT​

Adım 1: 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,
            successUrl = "https://merchant.example.com/payment/callback/success",
            failUrl = "https://merchant.example.com/payment/callback/fail"
        ),
        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,
    config = BexFullSdkConfig(mode = SdkMode.PAYMENT)
)

Adım 2: Ö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.

Hibrit SDK entegrasyon (yalnızca kart seçimi) — CARD_SELECTION_ONLY = true​

Hibrit entegrasyonda CARD_SELECTION_ONLY = true → SdkMode.CARD_SELECTION_ONLY kullanılır. Bu modda SDK ödeme akışını başlatmaz; kullanıcı kart seçer ve seçilen kart PaymentCallback.onCardSelected(...) ile uygulamanıza döner.

Adım 1: SDK başlatma​

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 bu modda zorunlu değildir
        environment = BexEnvironment.DEV
    ),
    callback = object : PaymentCallback {
        override fun onPaymentSuccess(result: PaymentResult) {
            // Bu modda ödeme yapılmadığı için normalde kullanılmaz
        }

        override fun onCardSelected(result: CardSelectionResult) {
            val selectedCard = result.selectedCard
            // Seçilen kart bilgisi ile kendi ödeme akışınızı başlatabilirsiniz
        }

        override fun onError(error: BexSdkError) {
            // Hata/iptal durumları burada ele alınır.
        }
    },
    config = BexFullSdkConfig(mode = SdkMode.CARD_SELECTION_ONLY)
)

Adım 2: Kart seçimi ekranını açma​

Seçenek 1: Tam ekran Activity

BexFullSdk.start()

Seçenek 2: Alt sayfa (Bottom Sheet)

BexFullSdk.showAsBottomSheet(activity = this)

Örnek Kullanım​

Bu bölümdeki örneklerde hangi callback’in hangi entegrasyon modunda kullanılacağı net olacak şekilde gösterilir:

  • Full SDK (SdkMode.PAYMENT): onPaymentSuccess kullanılır, onCardSelected kullanılmaz.
  • Hibrit SDK (CARD_SELECTION_ONLY = true → SdkMode.CARD_SELECTION_ONLY): onCardSelected kullanılır, onPaymentSuccess kullanılmaz.

Full SDK (PAYMENT) — 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,
                    successUrl = "https://merchant.example.com/payment/callback/success",
                    failUrl = "https://merchant.example.com/payment/callback/fail"
                ),
                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 onCardSelected(result: CardSelectionResult) {
                    // Full SDK (PAYMENT) modunda kullanılmaz.
                    // Bu callback yalnızca Hibrit modda (CARD_SELECTION_ONLY) kart seçildiğinde tetiklenir.
                }

                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"
    }
}

Hibrit SDK (CARD_SELECTION_ONLY) — Activity örneği​

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

        // Örn: kullanıcı kart seçsin, seçilen kartla sizin akışınız başlasın
        startCardSelection()
    }

    private fun startCardSelection() {
        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 bu modda zorunlu değildir
                environment = BexEnvironment.DEV
            ),
            callback = object : PaymentCallback {
                override fun onPaymentSuccess(result: PaymentResult) {
                    // Hibrit (CARD_SELECTION_ONLY) modunda kullanılmaz.
                    // Bu callback yalnızca Full SDK (PAYMENT) modunda ödeme tamamlandığında tetiklenir.
                }

                override fun onCardSelected(result: CardSelectionResult) {
                    val selectedCard = result.selectedCard
                    // Seçilen kart ile kendi ödeme akışınızı başlatın
                }

                override fun onError(error: BexSdkError) {
                    // Hata/iptal durumları burada ele alınır.
                }
            },
            config = BexFullSdkConfig(mode = SdkMode.CARD_SELECTION_ONLY)
        )

        BexFullSdk.start()
    }
}

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: Sonuç geri çağrısı. Full entegrasyonda (SdkMode.PAYMENT) onPaymentSuccess kullanılır. Hibrit entegrasyonda (CARD_SELECTION_ONLY = true →SdkMode.CARD_SELECTION_ONLY) ayrıca onCardSelected kullanılmalıdı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, /sdk/init API'sinden dönen currencySymbol ile tutarı birleştirerek gösterir (ör. «₺ 100,00 Öde»). API'den sembol dönmezse SdkPaymentInfo.currency kodundan yerel eşleşme kullanılır. 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. Ödeme başlatılırken paymentInfo.successUrl ve paymentInfo.failUrl de transaction init istekleriyle birlikte gönderilir; backend’iniz ödeme sürecinin tamamlanması veya başarısızlığı hakkında bu adresler üzerinden bilgilendirilir.

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,
    val successUrl: String = "",
    val failUrl: String = ""
)

Satıcı backend bildirim URL’leri: successUrl ve failUrl, ödeme işleminin sunucu tarafında tamamlanması veya başarısız kalması durumunda satıcı backend’inizin bilgilendirilmesi için kullanılır. SDK bu adresleri işlem başlatma (transaction init) API isteklerinin gövdesine ekler; bildirim, uygulama içi PaymentCallback geri çağrılarından bağımsız olarak backend’inize iletilir. SdkMode.PAYMENT modunda ödeme akışı başlatılırken her iki alan da API’ye iletilir.

  • successUrl: Ödeme süreci başarıyla tamamlandığında satıcı backend’inize yönlendirilecek veya çağrılacak bildirim adresi. Tam, erişilebilir bir URL (ör. HTTPS) olmalıdır. Varsayılan: "" (boş string).
  • failUrl: Ödeme süreci başarısız olduğunda, iptal edildiğinde veya tamamlanamadığında satıcı backend’inize iletilecek bildirim adresi. Varsayılan: "" (boş string).

Not: Bu URL’ler istemci tarafındaki onPaymentSuccess / onError geri çağrılarının yerine geçmez; mobil uygulama deneyimi için PaymentCallback kullanılmaya devam edilir. Backend bildirimleri sipariş durumu güncelleme, muhasebe veya webhook tabanlı entegrasyonlar için ayrıca tanımlanmalıdır.

  • currency: ISO 4217 para birimi kodu veya sayısal karşılığı kabul edilir. Alfabetik kod (ör. "TRY", "USD", "EUR") ya da sayısal kod (ör. "949" → Türk Lirası, "840" → ABD Doları) olarak geçilebilir; SDK bu değeri büyük harfe çevirerek /sdk/init isteğinde gönderir. API karşılık olarak currencySymbol (ör. ₺) döner; bu sembol SdkMode.PAYMENT modunda kart seçim ekranındaki ödeme butonunda otomatik olarak gösterilir (ör. «₺ 100,00 Öde»). API'den sembol dönmezse SDK, para birimi kodundan yerel bir eşleşme kullanmaya geri döner. Desteklenmeyen bir değer gönderilirse API code: 1049 hatasını döner ve onError içinde BexSdkError.Api olarak iletilir:

    {
      "error": {
        "title": "INVALID_CURRENCY",
        "code": 1049,
        "message": "Gönderilen para birimi desteklenmiyor.",
        "technicalMessage": "Currency değeri desteklenmiyor."
      }
    }

  • 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). İşlem başlatma isteğinde successUrl ve failUrl de birlikte gönderilir.

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.

Backend bildirim URL’leri: Ödeme tamamlandığında veya hata aldığında satıcı sunucunuzun bilgilendirilmesi gerekiyorsa SdkPaymentInfo.successUrl ve SdkPaymentInfo.failUrl alanlarını doldurun. Boş bırakıldığında SDK bu alanları yine de API’ye iletir; backend bildirimi almak için ortamınıza uygun tam URL’leri sağlamanız gerekir.