Servisler

SDK Initialization

SDK initialization entegrasyonun başlangıç noktasıdır. Ortak kullanılan alanlar burada bir kez tanımlanır.

Request Parametereleri

Parametre	Tip	Zorunlu	Açıklama
token	string	Required	Merchant backend tarafından üretilen bearer token.
merchantId	string	Required	Bex tarafından üretilen merchant unique değeri. (bu bilgi bex ekibi tarafından oluşturulup üye işyeri ile paylaşılacaktır).
gsmNo	string	Required	Son kullanıcı telefon numarası.
merchantUserId	string	Required	Merchant tarafından üretilen son kullanıcıya ait tekil değer.
environment	string	Required	Entegrasyonun gerçekleştireleceği ortam bilgisi.

Bu alanlar init sonrası SDK içinde saklanır ve Check Status, Link Account, Store Card, Start Payment ve Start Payment with Card Registration tüm client servislerinde otomatik taşınır.

Lifecycle Kuralları

SDK initialize edilmeden hiçbir client servisi çağrılamaz.
Token süresi dolarsa yeni token ile SDK yeniden init edilmelidir.
Kullanıcı değişirse yeni merchantUserId ve gsmNo ile tekrar init yapılmalıdır.
Complete Payment, Cancel, Refund ve Unlink servisleri client değil merchant backend tarafından çağrılır.

Generate Token

Generate Token servisi yanlızca B2B(backend-to-backend) çalışır. Client bu servise doğrudan erişemez. Tüm token üretimi Merchant backend üzerinden yapılır ve üretilen Bearer token bilgisi güvenli şekilde client SDK’ya aktarılır.

İş Kuralları

Sadece Merchant backend çağırabilir.
Token en fazla 15 dakika geçerlidir. 15 dakikalık token süresi dolduğunda Merchant Backend'in otomatik olarak tekrar generateToken servisine gidip yeni bir token alacak şekilde ("Token Refresh" mantığı) kurgulanması akışın sürekliliği için kritiktir.
Token client SDK çağrılarında Authorization Bearer olarak taşınır.
Servis IP secure çalışır; erişim izni network seviyesinde yalnızca önceden tanımlanmış sabit IP adresleri için verilir.
Üye işyerinin Generate Token servisini çağıracak sabit IP bilgilerini önceden BEX Dijital Entegrasyon ekibi ile paylaşması gerekir.
Tanımlı IP bilgilerinde değişiklik olacaksa, erişim kesintisi yaşanmaması için değişiklik öncesi Dijital Entegrasyon ekibine bilgi vermelidir.

Request Parametereleri

Parametre	Tip	Zorunlu	Kısıtlar	Açıklama
merchantId	string	Required	Max Length = 36	Bex tarafından üretilen merchant unique değeri. (bu bilgi bex ekibi tarafından oluşturulup üye işyeri ile paylaşılacaktır).
gsmNo	string	Required	Max Length = 10	Son kullanıcı telefon numarası.
merchantUserId	string	Required	Max Length = 255	Merchant tarafından üretilen son kullanıcıya ait tekil değer.

Endpoint

POST https://bexmerchant-dev.bkmtest.com.tr/merchant/generateToken

Örnek Request

curl -X POST \
  https://bexmerchant-dev.bkmtest.com.tr/merchant/generateToken \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 72275e90-28ee-4df2-a3bb-79d3d92adfe1' \
  -H 'accept: */*' \
  -H 'cache-control: no-cache' \
  -d '{
    "merchantId": "11111111-1111-1111-1111-111111111112",
    "gsmNo": "5374407074",
    "merchantUserId": "123"
}'

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
token	Bearer olarak kullanılacak token değeri.
id	BEX tarafında kullanılan işleme ait benzersiz değer.
error(object)	Hatalı response durumunda doldurulan nesne.
title	Hata başlığı.
code	Hata kodu.
message	Hatanın son kullanıcıya gösterilecek açıklaması.
technicalMessage	Hatanın Teknik açıklaması.
priority	Hata öncelik sırası.

Örnek Başarılı Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJDb21pbmdUeXBlIjoiTWVyY2hhbnQiLCJVSUQiOiIxMTExMTExMS0xMTExLTExMTEtMTExMS0xMTExMTExMTExMTIiLCJpZGVudGlmaWVyIjoiNTM3NDQwNzA3NCIsInByb2Nlc3NJZCI6ImJlMWMxMGE1LTY1OGMtNGRkNy1hYTRjLWUwYWFjYjI3YzdkNCIsIlJ1bGUiOiJNZXJjaGFudENvbnRyb2wiLCJtZXJjaGFudFVzZXJJZCI6IjEyMyIsImV4cCI6MTc4MDg2MjY2OSwiaWF0IjoxNzc0ODYyNzI5fQ.GS1RQFWKvozfn7itpKctKz_HWJTYRZunQD6GVbc4aC0",
    "id": "be1c10a5-658c-4dd7-aa4c-e0aacb27c7d4"
  }
}

Örnek Hatalı Response

{
  "error": {
    "title": "MERCHANT_USER_ID_IS_REQUIRED",
    "code": 1013,
    "message": "İşleminizi şu anda gerçekleştiremiyoruz.",
    "technicalMessage": "merchantUserId parametresi eksik veya hatalı.",
    "priority": 0
  }
}

CheckStatus

Bu servisi son kullanıcının BEX sisteminde güncel hesap durumunu sorgulamak, üye işyeri ile hesap eşleştirme ve kart listeleme gibi entegrasyonları sağlamak amacıyla kullanılacaktır.

Akış Yönlendirme Notları

Kullanıcının son kayıtlı kartının silinmiş olması durumunda ilgili BEX hesabı da kaldırılmış olabilir. Bu durumda Check Status sonucu hesap bulunamadı senaryosuna dönebilir.
Check Status servisi USER_HAS_NOT_VALID_CARD_FOR_ECOMMERCE hatası ile bilrlikte kart eklenmesi gerektiğini belirten bir hata mesajı dönerse Merchant kullanıcıyı Kart ekleme veya Kart kaydederek ödeme akışına yönlendirmelidir.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Check Status çağrısında otomatik olarak kullanılır.

token
merchantId
merchantUserId
gsmNo

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Servis özelinde gönderilen alanlar

Bu servis ek request parametresine ihtiyaç duymaz.

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
token	Bearer olarak kullanılacak token değeri.
merchantName	İşyeri ismi.
resultCode	Hata kodu.
resultMessage	Hatanın son kullanıcıya gösterilecek açıklaması.
errorTitle	Hata başlığı.
error(object)	Hatalı response durumunda doldurulan nesne.
title	Hata başlığı.
code	Hata kodu.
message	Hatanın son kullanıcıya gösterilecek açıklaması.
technicalMessage	Hatanın teknik açıklaması.
priority	Hata öncelik sırası.
screen	Bir sonraki önerilen akış.
cards(object)	Başarılı response durumunda doldurulan nesne.
cardId	İlgili kartın sistemdeki benzersiz referans değeri.
maskCardNumber	Maskeli kart numarası.
cardAlias	İlgili kartın sistemdeki takma adı.
binValue	Kartın ilk 6 veya ilk 8 hanesi.
imageUrl	İlgili kartın resmi.
createdTime	Oluşturulma tarihi.
bankInformation(object)	Kartın banka bilgileri nesnesi.
cardType	Kart tipi (Debit/Credit).
cardBrandType	Marka tipi.
cardBrand	Kartın markası(TROY/VISA/MASTERCARD).
bankShortName	Banka kısa açıklaması.
bankCode	Banka kodu (EFT kod).

Response Davranışı

Token Yönetimi: Check Status response’unda dönen token, sonraki servislerde kullanılmak üzere SDK tarafından otomatik olarak yönetilir. Client’ın bu değeri manuel olarak saklaması veya request’e eklemesi gerekmez.
Ekran Yönlendirme: Response içinde yer alan screen alanı, kullanıcıya gösterilmesi gereken bir sonraki ekranı belirtir. Bu alan BEX tarafından önerilen akış yönlendirmesini temsil eder.

Response içerisinde “screen” alanı "PartialRegisterScreen" olarak döndüğünde akış kart ekleme ekranına yönlendirilmelidir. Servis detaylarına StoreCard sayfasından erişebilirsiniz.

Response içerisinde “screen” alanı "LinkScreen" olarak döndüğünde akış hesap bağlama ekranına yönlendirilmelidir. Servis detaylarına LinkAccount sayfasından erişebilirsiniz.

Örnek Olası Sonuç Durumları:

Hesap yok

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9…",
    "resultCode": 1001,
    "resultMessage": "Kullanıcı Bulunamadı.",
    "errorTitle": "USER_NOT_FOUND",
    "screen": "PartialRegisterScreen"
  }
}

Hesap var, kart var, link yok

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9…",
    "merchantName": "Odeme Gecidi",
    "resultCode": 1002,
    "resultMessage": "İşleminizi şu anda gerçekleştiremiyoruz.",
    "errorTitle": "USER_NOT_LINKED",
    "screen": "LinkScreen"
  }
}

Hesap var, kart var, link olan kullanıcı

{
    "data": {
        "cards": [
            {
                "cardId": "019c2df9-1eef-7d66-9a38-c060f516b04f",
                "maskCardNumber": "650173******1396",
                "cardAlias": "test",
                "binValue": "65017385",
                "imageUrl": "https://img-bkmexpress.mncdn.com/BexpLogos/banks/mobil/3/65026800_ZiraatBankkartTroy_540x336.png",
                "createdTime": "2026-02-05 16:23:47.05353",
                "bankInformation": {
                    "cardType": "CreditCard",
                    "cardBrandType": "Marka Yok",
                    "cardBrand": "Troy",
                    "bankShortName": "İŞBANK",
                    "bankCode": "0064"
                },
                "active": true
            },
            {
                "cardId": "019cd2a9-8dda-7474-bd33-532ca70d2d78",
                "maskCardNumber": "650083******6850",
                "cardAlias": "test",
                "binValue": "65008307",
                "imageUrl": "https://img-bkmexpress.mncdn.com/BexpLogos/banks/mobil/3/65026800_ZiraatBankkartTroy_540x336.png",
                "createdTime": "2026-03-09 15:54:13.203414",
                "bankInformation": {
                    "cardType": "Debit",
                    "cardBrandType": "Bankart Combo",
                    "cardBrand": "Troy",
                    "bankShortName": "ZİRAATBANK",
                    "bankCode": "0010"
                },
                "active": true
            }
        ],
            "screen": "DashboardScreen"
    }
}

Örnek Hatalı Response

{
  "error": {
    "title": "MERCHANT_USER_ID_MISMATCH",
    "code": 1012,
    "message": "İşleminizi şu anda gerçekleştiremiyoruz.",
    "technicalMessage": "Token ve request merchantUserId uyuşmuyor.",
    "priority": 0
  }
}

LinkAccount

Son kullanıcının hesabı ve kayıtlı kartlarını ilgili işyerinde kullanabilmesi için merchant ile BEX hesabını ilişkilendirir. Tek seferlik çalışır ve kartın bankasından kart sahibine iletilen issuer OTP ile doğrulanır.

SDK Davranışı

SDK checkStatus servisinden dönen token bilgisini otomatik olarak request’e ekler.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Link Account çağrısında otomatik olarak kullanılır.

token
merchantId
merchantUserId
gsmNo

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Servis özelinde gönderilen alanlar

Bu servis ek request parametresine ihtiyaç duymaz.

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
transactionId	İşleme özel üretilen tekil değer.
sender	OTP’yi ileten issuer banka adı.
durationTimeInSeconds	OTP’nin aktif olma süresi.
otpLength	OTP uzunluğu
gsmNo	OTP’nin iletildiği telefon numarası.
otpRefNo	Banka tarafından üretilen ve kart sahibine ekranda gösterilen, her SMS’de değişecek random bilgidir.
screen	Bir sonraki önerilen akış.
countryCode	Ülke kodu.
emailAddress	Son kullanıcının mail adresi.
channel	OTP doğrulamanın yapıldığı kanal bilgisi. I-Issuer
timestamp	İşlem tarih-saat bilgisi.
error(object)	Hatalı response durumunda doldurulan nesne.
title	Hata başlığı.
code	Hata kodu.
message	Hatanın son kullanıcıya gösterilecek açıklaması.
technicalMessage	Hatanın teknik açıklaması.

Response Davranışı

Ekran yönlendirme: Response içinde yer alan screen alanı, kullanıcıya gösterilmesi gereken bir sonraki ekranı belirtir. Bu alan BEX tarafından önerilen akış yönlendirmesini temsil eder.

Örnek Başarılı Response

{
  "data": {
    "transactionId": "e55937bd-a2c8-4532-bd42-882a51d74f4c",
    "sender": "ZİRAAT BANKASI",
    "durationTimeInSeconds": 60,
    "otpLength": 6,
    "gsmNo": "5555555555",
    "otpRefNo": "XI010GO6L3",
    "screen": "EnterOtpScreen",
    "countryCode": "90",
    "channel": "I",
    "timestamp": 20260405-23:23:48
  }
}

Response içerisinde “screen” alanı "EnterOtpScreen" olarak döndüğünde akış OTP doğrulama ekranına yönlendirilmelidir. Yine aynı response içerisinde yer alan “transactionId” ve “refNo” değerleri bir sonraki adımda çağırılacak VerifyOTP servisi için kullanılacaktır. Servis detaylarına VerifyOTP sayfasından erişebilirsiniz.

Örnek Hatalı Response

{
  "error": {
    "title": "MERCHANT_USER_ID_MISMATCH",
    "code": 1012,
    "message": "İşleminizi şu anda gerçekleştiremiyoruz.",
    "technicalMessage": "Token ve request merchantUserId uyuşmuyor.",
    "priority": 0
  }
}

StoreCard

Kullanıcının yeni kartını BEX hesabına güvenli şekilde kaydetmek için kullanılır. Kart verisi yalnızca SDK tarafından sağlanan güvenli alanlardan alınır, SDK içinde şifrelenir ve servis çağrısında otomatik olarak eklenir.

İş Kuralları

Kart bilgileri yalnızca SDK’nın sağladığı güvenli alanlar üzerinden alınmalıdır.
Merchant kart numarası, son kullanma tarihi veya diğer hassas kart verilerini plaintext olarak okumamalı, loglamamalı, saklamamalı veya üçüncü taraf sistemlere aktarmamalıdır.
Hassas kart verisi SDK içinde şifrelenir ve Kart Ekle (Store Card) servisine yalnızca şifrelenmiş payload otomatik olarak iletilir.
Merchant uygulaması kart datasını manuel olarak request body içinde oluşturmamalı veya SDK dışında şifreleme süreci yürütmemelidir.
Kart kaydı issuer doğrulama kurallarına bağlı olarak OTP doğrulaması yapılarak eklenebilir. OTP doğrulama tamamlanmadan kart kaydı başarılı sayılmaz.
SDK initialize edilmeden veya SDK oturumu geçersizken Kart Ekle (Store Card) servisi çağrılamaz.

BEX platformu hassas verilerin işlenmesi ve saklanması süreçlerinde PCI DSS (Payment Card Industry Data Secureity Standart) gereksinimlerine uygun şekilde tasarlanmıştır.

SDK Davranışı

SDK checkStatus servisinden dönen token bilgisini otomatik olarak request’e ekler.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Store Card çağrısında otomatik olarak kullanılır.

token
merchantId
merchantUserId
gsmNo

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Sözleşmeler ve Kullanıcı Onayı

Kart ekleme akışında kullanıcıya gösterilmesi gereken sözleşme ve onay bilgileri BEX tarafından döndürülür. SDK Initialization yapıldıktan sonra onay bekleyen sözleşmeler response içerisinde pendingAgreements ve ilgili açıklama alanları ile iletilir. Bu sözleşmeler için kullanıcı onayı SDK tarafından sağlanan checkbox komponenti ile alınmalıdır.

Merchant sözleşme onayı gereken senaryolarda SDK’nın sağladığı checkbox bileşenini UI akışına dahil etmelidir. Gerekli onay alınmadan kart ekleme akışı tamamlanamaz.

Response içerisinde type alanı "AGREEMENT" olarak döndüğünde UI’da checkbox gösterilmelidir.

Response içerisinde type alanı “INFO” olarak döndüğünde (örneğin KVKK) içerik kullanıcıya bilgilendirme metni olarak gösterilmeli checkbox onayının bir parçası olmamalıdır.

pendingAgreements Response Parametereleri

Parametre	Açıklama
id	Sözleşme Id'si
code	Sözleşme Kodu KVKK → KVKK TERMS_OF_USE → Kullanıcı Sözleşmesi MARKETING → Ticari Elektronik İleti İzni
type	Sözleşme Tipi (checkbox çıkmasını belirler) AGREEMENT → checkbox yer alır. (Örn: Kullanıcı Sözleşmesi, Ticari Elektronik İleti İzni) INFO → checkbox yer almaz. (Örn: KVKK)
contentType	Gösterim için içerik tipi HTML URL
title	Sözleşmenin gösterileceği sayfada kullanılacak olan başlık bilgisi
content	Sözleşme Metinleri (URL ise URL bilgisi, raw html ise raw html değeri)
labelHighlight	Sözleşme onayı için gösterilen metinde highlight edilmesi beklenen kelime veya kelime grubunu iletir. Örn: "Kullanıcı Sözleşmesini okudum, onaylıyorum." cümlesi için labelHighlight parametre değeri olarak "Kullanıcı Sözleşmesi" iletilebilir.
label	Sözleşme onayı için gösterilen metin. Örn: "Kullanıcı Sözleşmesini okudum, onaylıyorum."
mandatory	Onay ve gösterim zorunlu mu? true / false Kullanıcı sözleşmesi ve KVKK için true Ticari Elektronik İleti İzni için false

Örnek pendingAgreements Response:

{
 "pendingAgreements": [
 {
 "id": 1,
 "code": "TERMS_OF_USE",
 "type": "AGREEMENT",
 "contentType": "HTML",
 "title": "Kullanıcı Sözleşmesi",
 "content": "<p>Kullanım Koşulları ...</p>",
 "labelHighlight": "Kullanıcı Sözleşmesi",
 "label": "Kullanıcı Sözleşmesini onaylıyorum.",
 "mandatory": true
 },
 {
 "id": 2,
 "code": "KVKK",
 "type": "INFO",
 "contentType": "URL",
 "title": "BKM EXPRESS KVKK Aydınlatma Metni",
 "content": "https://bkmexpress.com.tr/KVKK",
 "labelHighlight": "",
 "label": "",
 "mandatory": true
 }
 ]
}

Zorunlu sözleşmeler onaylanmadığı takdirde MISSED_MANDATORY_AGREEMENT hatası alınacaktır.

Request Parametereleri

Parametre	Tip	Zorunlu	Açıklama
aliasName	string	Required	Karta verilen takma ad. Örn: Kredi Kartım
tokenizedPan	string	Required	SDK tarafında Güvenli alanlardan alınan ve şifrelenen kart verisi payload’ı.

Response Parametreleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
transactionId	İşleme özel üretilen tekil değer.
sender	OTP’yi ileten issuer banka adı.

Response Davranışı

Ekran Yönlendirme : Response içinde yer alan screen alanı, kullanıcıya gösterilmesi gereken bir sonraki ekranı belirtir. Bu alan BEX tarafından önerilen akış yönlendirmesini temsil eder.

Örnek Başarılı Response

{
  "data": {
    "transactionId": "e55937bd-a2c8-4532-bd42-882a51d74f4c",
    "sender": "ZİRAAT BANKASI",
    "durationTimeInSeconds": 60,
    "otpLength": 6,
    "gsmNo": "5555555555",
    "otpRefNo": "XI010GO6L3",
    "screen": "EnterOtpScreen",
    "countryCode": "90",
    "channel": "I",
    "timestamp": 20260405-23:23:48
  }
}

Response içerisinde “screen” alanı "EnterOtpScreen" olarak döndüğünde akış OTP doğrulama ekranına yönlendirilmelidir. Yine aynı response içerisinde yer alan “transactionId” ve “refNo” değerleri bir sonraki adımda çağırılacak VerifyOTP servisi için kullanılacaktır. Servis detaylarına VerifyOTP sayfasından erişebilirsiniz.

Örnek Başarılı Response

{
  "error": {
    "title": "GSM_NO_LENGTH_MUST_BE_10_DIGITS",
    "code": 1008,
    "message": "İşleminizi şu anda gerçekleştiremiyoruz.",
    "technicalMessage": "gsmNo 10 haneli olmalıdır.",
    "priority": 0
  }
}

VerifyOTP

OTP doğrulama gerektiren akışlarda kullanılır. OTP süresi, deneme limiti ve tekrar gönderim davranışı ürün kurallarına göre yönetilir.

İş Kuralları

OTP yalnızca bir kez kullanılabilir.
OTP süresi 180 saniyedir.
OTP süresi dolduğunda doğrulama yapılamaz, yeni OTP akışı başlatılmalıdır.
OTP doğrulaması yalnızca oluşturulduğu işlem (transactionId/refNo) için geçerlidir. Farklı bir işlemde kullanılamaz.
Aynı transactionId ve refNo ile maksimum 3 OTP doğrulama denemesi yapılabilir.
OTP doğrulama işlemi banka tarafından yapılmaktadır.

OTP doğrulama süreci, bankacılık güvenlik standartlarına uygun olarak yönetilir ve fraud önleme mekanizmaları ile korunur.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Verify OTP çağrısında otomatik olarak kullanılır.

token

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Request Parametereleri

Parametre	Tip	Zorunlu	Kısıtlar	Açıklama
otpValue	string	Required	Max:10	Son kullanıcının girdiği OTP değeri.
transactionId	string	Required	Max:36	İşleme özel üretilen tekil değer.
otpRefNo	string	Required	Max:20	Banka tarafından üretilen ve kart sahibine ekranda gösterilen, her SMS’de değişecek random bilgidir.

Örnek Request

{
  "otpValue": "123456",
  "otpRefNo": "5EABN0K9DW",
  "transactionId": "c95d8b53-3916-4d25-b3fe-64b02c741be1"
}

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
token	Bearer olarak kullanılacak token değeri.
screen	Bir sonraki önerilen akış.
error(object)	Hatalı response durumunda doldurulan nesne.
title	Hata başlığı.
code	Hata kodu.
message	Hatanın son kullanıcıya gösterilecek açıklaması.
technicalMessage	Hatanın teknik açıklaması.
priority	Hata öncelik sırası.

Response Davranışı

Token Yönetimi : Verify OTP response’unda dönen token, sonraki servislerde kullanılmak üzere SDK tarafından otomatik olarak yönetilir. Client’ın bu değeri manuel olarak saklaması veya request’e eklemesi gerekmez.
Ekran Yönlendirme : Response içinde yer alan screen alanı, kullanıcıya gösterilmesi gereken bir sonraki ekranı belirtir. Bu alan BEX tarafından önerilen akış yönlendirmesini temsil eder.

Örnek Başarılı Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "screen": "WalletScreen"
  }
}

Response içerisinde “screen” alanı "WalletScreen" olarak döndüğünde akış bir sonraki adımda Check Status servisine yönlendirilmelidir. Yine aynı response içerisinde yer alan “token” değeri SDK tarafından otomatik olarak saklanır ve yönetilir.

Örnek Hatalı Response

{
  "error": {
    "title": "OTP_CODE_WRONG",
    "code": 9,
    "message": "Doğrulama Kodunu yanlış girdiniz. Lütfen tekrar deneyiniz.",
    "technicalMessage": "Doğrulama Kodunu yanlış girdiniz. Lütfen tekrar deneyiniz.",
    "priority": 0
  }
}

ResendOTP

OTP süresi dolduğunda veya son kullanıcı SMS’i alamadığında, mevcut doğrulama işlemini bozmadan aynı işlem için yeni OTP üretilmesini sağlar.

İş Kuralları

Resend OTP işlemi yalnızca mevcut doğrulama işlemi (transactionId/refNo) için çalışır.
Resend OTP yeni bir işlem oluşturmaz; mevcut OTP doğrulama akışını devam ettiir.
Yeni OTP üretildiğinde önceki OTP geçersiz hale gelir ve tekrar kullanılamaz.
Her resend sonrası OTP geçerlilik süresi yeniden başlatılır.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Resend OTP çağrısında otomatik olarak kullanılır.

token

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Request Parametereleri

Parametre	Tip	Zorunlu	Kısıtlar	Açıklama
otpValue	string	Required	Max:10	Son kullanıcının girdiği OTP değeri.
transactionId	string	Required	Max:36	İşleme özel üretilen tekil değer.
otpRefNo	string	Required	Max:20	Banka tarafından üretilen ve kart sahibine ekranda gösterilen, her SMS’de değişecek random bilgidir.

Örnek Request

{
  "otpRefNo": "5EABN0K9DW",
  "transactionId": "c95d8b53-3916-4d25-b3fe-64b02c741be1"
}

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
token	Bearer olarak kullanılacak token değeri.
screen	Bir sonraki önerilen akış.
error(object)	Hatalı response durumunda doldurulan nesne.
title	Hata başlığı.
code	Hata kodu.
message	Hatanın son kullanıcıya gösterilecek açıklaması.
technicalMessage	Hatanın teknik açıklaması.
priority	Hata öncelik sırası.

Response Davranışı

Token Yönetimi : Verify OTP response’unda dönen token, sonraki servislerde kullanılmak üzere SDK tarafından otomatik olarak yönetilir. Client’ın bu değeri manuel olarak saklaması veya request’e eklemesi gerekmez.
Ekran Yönlendirme : Response içinde yer alan screen alanı, kullanıcıya gösterilmesi gereken bir sonraki ekranı belirtir. Bu alan BEX tarafından önerilen akış yönlendirmesini temsil eder.

Örnek Başarılı Response

{
  "otpRefNo": "5EABN0K9DW",
  "transactionId": "c95d8b53-3916-4d25-b3fe-64b02c741be1"
}

Response içerisinde “screen” alanı "WalletScreen" olarak döndüğünde akış bir sonraki adımda Check Status servisine yönlendirilmelidir. Yine aynı response içerisinde yer alan “token” değeri SDK tarafından otomatik olarak saklanır ve yönetilir.

Örnek Hatalı Response

{
  "error": {
    "title": "OTP_EXPIRED",
    "code": 8,
    "message": "İşleminizi şu anda gerçekleştiremiyoruz.",
    "technicalMessage": "OTP süresi dolmuş.",
    "priority": 0
  }
}

CardDelete

Son kullanıcının BEX hesabında kayıtlı kartını silmek için kullanılır.

İş Kuralları

Kart silme işlemi yalnızca kayıtlı kartlar için yapılabilir.
Silinen kart kayıtlı kart listesinde tekrar gösterilmez.
Kart silme işlemi geri alınamaz, kartın tekrar kullanılabilmesi için yeniden kart ekleme akışı çalıştırılmalıdır.
Kart silme işlemi başarılı olduğunda güncel kayıtlı kart listesi response içeriğinde iletilir.

Silme Davranışı

BEX hesabı en az bir kayıtlı kart varlığına bağlı olarak tutulur. Bu nedenle kullanıcıya ait son kart silindiğinde, ilgili BEX hesabı da aktif kayıtlı kart kalmadığı için sistemden kaldırılır.
Sonraki işlemlerde kullanıcı Merchant iş akış modeline göre yeniden kart ekleme veya kart kaydederek ödeme senaryosuna yönlendirilmelidir.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Card Delete çağrısında otomatik olarak kullanılır.

token
merchantId

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Request Parametereleri

Parametre	Tip	Zorunlu	Kısıtlar	Açıklama
cardId	string	Required	UUID	İlgili kartın sistemdeki benzersiz referans değeri.

Örnek Request

{
  "cardId": "019d2a26-88f9-7621-84b9-e7882569a3bd"
}

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
cards(object)	Başarılı response durumunda doldurulan nesne.
cardId	İlgili kartın sistemdeki benzersiz referans değeri.
maskCardNumber	Maskeli kart numarası.
cardAlias	İlgili kartın sistemdeki takma adı.
binValue	Kartın ilk 6 veya ilk 8 hanesi.
imageUrl	İlgili kartın resmi.
createdTime	Oluşturulma tarihi.
bankInformation(object)	Kartın banka bilgileri nesnesi.
cardType	Kart tipi (Debit/Credit).
cardBrandType	Marka tipi.
cardBrand	Kartın markası(TROY/VISA/MASTERCARD).
bankShortName	Banka kısa açıklaması.
bankCode	Banka kodu (EFT kod).

Örnek Başarılı Response

{
    "data": {
        "cards": [
            {
                "cardId": "019c2df9-1eef-7d66-9a38-c060f516b04f",
                "maskCardNumber": "650173******1396",
                "cardAlias": "test",
                "binValue": "65017385",
                "imageUrl": "https://img-bkmexpress.mncdn.com/BexpLogos/banks/mobil/3/65026800_ZiraatBankkartTroy_540x336.png",
                "createdTime": "2026-02-05 16:23:47.05353",
                "bankInformation": {
                    "cardType": "CreditCard",
                    "cardBrandType": "Marka Yok",
                    "cardBrand": "Troy",
                    "bankShortName": "İŞBANK",
                    "bankCode": "0064"
                },
                "active": true
            },
            {
                "cardId": "019cd2a9-8dda-7474-bd33-532ca70d2d78",
                "maskCardNumber": "650083******6850",
                "cardAlias": "test",
                "binValue": "65008307",
                "imageUrl": "https://img-bkmexpress.mncdn.com/BexpLogos/banks/mobil/3/65026800_ZiraatBankkartTroy_540x336.png",
                "createdTime": "2026-03-09 15:54:13.203414",
                "bankInformation": {
                    "cardType": "Debit",
                    "cardBrandType": "Bankart Combo",
                    "cardBrand": "Troy",
                    "bankShortName": "ZİRAATBANK",
                    "bankCode": "0010"
                },
                "active": true
            }
        ]
    }
}

Örnek Hatalı Response

{
  "error": {
    "title": "CARD_NOT_FOUND",
    "code": 6,
    "message": "Kart bulunamadı.",
    "technicalMessage": "Kart bulunamadı.",
    "priority": 0
  }
}

Start Payment

Kayıtlı kart ile ödeme akışını başlatır. Güvenlik modeli OTP / 3D olarak başlatılabilir. Finansal işlem bu aşamada tamamlanmaz ve doğrulama Complete Payment finansallaştırılır.

Güvenlik Modeli

BEX güvenlik tipi seçiminde hem sistem varsayılanlarını hem de merchant istek bazlı yönlendirme davranışını destekler.

Varsayılan Davranış

paymentSecurity gönderilmezse sistem kuralı uygulanır.
Merchant sistem parametrelerine threshold tanımı yapılabilir. Örneğin 0–1000 TL arası OTP, 1000 TL ve üzeri 3D.
Merchant için tanımlı güvenlik profili varsayılan akışı belirler.

İstek Bazlı Yönlendirme

paymentSecurity gönderilirse sistem kuralı override edilir.
Override yalnızca merchant için izinli güvenlik tipleri ile sınırlıdır.
Merchant isterse her işlemi paymentSecurity ile yönlendirebilir.

Yönlendirme Stratejisi

BEX ödeme routing davranışında hem sistem varsayılanlarını hem de merchant istek bazlı yönlendirme davranışını destekler.

Varsayılan Yönlendirme

On-us eşleşmesi varsa işlem öncelikle ilgili POS’a yönlendirilir.
On-us eşleşmesi yoksa merchant için tanımlı default POS kullanılır.

İstek Bazlı Yönlendirme

bankCode veya posCode alanları ile routing override edilebilir.
Override yalnızca merchant için tanımlı ve izinli POS seti içinde çalışır.

Sipariş Yönetimi

BEX orderId alanında hem merchant-controlled hem system-managed modları destekler.

Otomatik Mod

Merchant orderId göndermezse BEX tüm sanal pos bankaların kurallarına uygun orderId üretir.
Üretilen orderId ödeme tamamlama response'unda merchant’a döner.

Manuel Mod

Merchant orderId gönderirse BEX bu alanı değiştirmeden bankaya iletir.
Bankadan format hatası dönerse hata merchant’a aynı şekilde iletilir.

Hash Yönetimi

3D ödeme akışlarında bankadan dönen hash, hashParams ve benzeri doğrulama alanları normalde merchant tarafından kontrol edilir. BEX bu kontrolü merchant adına gerçekleştirebilir ve ek entegrasyon yükünü azaltır.

Varsayılan Davranış

3D doğrulama sonucunda bankadan gelen hash ve hashParams alanları BEX backend tarafından alınır.
BEX merchant adına gerekli hash doğrulamasını gerçekleştirir.
Bu sayede merchant tarafında ek hash hesaplama zorunlu olmaz.
Doğrulama başarılı ise merchant backend doğrudan Ödemeyi Tamamla (Complete Payment) çağrısına geçebilir.

İsteğe Bağlı Doğrulama

Merchant isterse bankadan gelen hash, hashParams ve ilgili form alanlarını yine response veya callback içinde alabilir.
Merchant her bankanın belirlemiş olduğu standartta hash hesaplamasını kendi tarafında gerçekleştirir.
BEX tarafından yapılan doğrulama ile merchant tarafındaki doğrulama birlikte kullanılabilir.

BEX'in sunduğu varsayılan modelde hash doğrulama yükü merchant üzerinden alınır. Ancak merchant isterse kendi kontrolünü sürdürebilir.

İş Kuralları

Start Payment servisi yalnızca ödeme doğrulama akışını başlatır; finansal işlem bu aşamada tamamlanmaz.
Güvenlik akışı paymentSecurity parametresine göre belirlenir.
- TDS: 3D secure doğrulama
- OTP: OTP doğrulama
- NONE: Herhangi bir doğrulama yapılmaz
Merchant request içinde paymentSecurity gönderirse işlem bu değere göre yönlendirilir.
Merchant request içinde paymentSecurity göndermezse sistem, işyeri için tanımlı güvenlik kuralına göre akışı belirler. Örneğin 0–1000 TL arası işlemler OTP, 1000 TL ve üzeri işlemler 3D olarak başlatılabilir.
Request içinde gönderilen paymentSecurity değeri, mevcut sistem threshold kuralının üzerine yazabilir ve ödeme akışı gönderilen değere göre başlatılır.
On-us yönlendirme yapısında, ödeme kartına ait eşleşen sanal POS bilgisi bulunduğunda işlem öncelikle ilgili POS’a yönlendirilir.
On-us eşleşmesi bulunmazsa işlem merchant için tanımlı default POS üzerinden devam eder.
Merchant request içinde bankCode veya benzeri bir routing parametresi gönderirse, ödeme sistemde tanımlı ilgili merchant POS üzerinden geçirilebilir.
Aynı bankadan birden fazla pos olması durumunda bankCode ile beraber posCode iletilmesi beklenir. İletilen posCode değerine tanımlı pos üzerinden ödeme geçirilebilir.
OrderId merchant tarafından gönderilirse BEX bu alanı format kontrolü yapmadan bankaya iletir. OrderId kaynaklı hata oluşursa hata merchant’a aynı şekilde iletilir.
Önerilen akışta orderId merchant tarafından gönderilmezse BEX ilgili bankanın uzunluk ve karakter kurallarına uygun bir orderId üretir, bankaya iletir ve response içinde kullanılan orderId bilgisini merchant’a döner.
Hash doğrulama işlemi bankadan dönen verinin bütünlüğünü sağlamak adına zorunludur. BEX önerilen akışta bu doğrulamayı Merchant adına gerçekleştirir ve banka bazlı farklılıkları merkezi olarak yönetir.
Merchant banka bazlı farklılaşan hash doğrulama işlemini gerçekleştirmek isterse BEX bankadan gelen hash hesaplama parametrelerini merchant’a iletir.
3D Secure akışlarında bankadan dönen mdSuccess, hash, hashParams ve ilgili doğrulama alanlarının Merchant tarafına iletilebilmesi için successUrl ve errorUrl parametreleri sağlanmalıdır.
- SuccessUrl ve errorUrl alanları yalnızca HTTPS formatında olmalı ve POST methodu ile veri kabul edecek şekilde tasarlanmalıdır.
- Merchant successUrl ve errorUrl alanlarını her işlem için dinamik belirleyebilir. Sipariş bazlı callback URL kullanımı desteklenir.
TransactionId alanı BEX tarafında aynı işlemin başlatma ve tamamlanma adımlarını eşleştirmek ve işlem bütünlüğünü sağlamak için kullanır.
- TransactionId alanı işlem özelinde tekil olmalıdır ve UUID benzeri benzersiz bir formatta kullanılması önerilir.
- Aynı transactionId alanı ödeme başlatma ve ödeme tamamlama adımlarında birlikte kullanılmalıdır.
- Tekrar eden, çakışan veya işlem bağlamı ile uyumsuz transactionId alanı hata ile sonuçlanabilir.

SDK Init üzerinden alınan alanlar

Aşağıdaki alanlar SDK init sırasında bir kez tanımlanır ve Start Payment çağrısında otomatik olarak kullanılır.

token
merchantId
merchantUserId
gsmNo

Request detaylarını incelemek için SDK Initialization sayfasını inceleyebilirsiniz.

Request Parametereleri

Parametre	Tip	Zorunlu	Kısıtlar	Açıklama
cardId	string	Required	Max: 36	İlgili kartın sistemdeki benzersiz referans değeri.
orderId	string	Optional	Max: 255	Ödeme işlemine ait sipariş numarası.
amount	double	Required		Ödemenin tutar bilgisi Format: 12.00 12.54 122345.34
installmentCount	number	Required	Max: 2	Taksit bilgisi. Tek çekim işlemlerde “1” gönderilmelidir.
transactionId	string	Required	Max: 36	Her işlem özelinde üretilmesi beklenen benzersiz değer.
transactionDate	string	Required		Tarih-saat bilgisi. ISO 8601 Format: YYYY-MM-DDTHH:mm:ss.sss
currency	string	Required	Max:3	Ödemenin tahsil edileceği para birimi 949 -TRY
paymentSecurity	enum	Optional		Ödeme güvenlik yöntemi TDS OTP NONE
successUrl	string	Required		Ödeme işlemi başarılı olursa yönlenecek sayfa adresi.
errorUrl	string	Required		Ödeme işlemi başarısız olursa yönlenecek sayfa adresi.
paymentToken

Örnek Request

{
  "amount": 202.5,
  "cardId": "019cd2a9-8dda-7474-bd33-532ca70d2d78",
  "currency": "TRY",
  "installmentCount": 1,
  "merchantId": "11111111-1111-1111-1111-111111111114",
  "gsmNo": "5052148528",
  "merchantUserId": "113355771",
  "orderId": "DEMO-159918238",
  "transactionId": "a19127c2-aea8-436b-8d71-eefd43e82ae9",
  "transactionDate": "2026-04-06T23:23:09.507+03:00"
}

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
tdsUrl	Banka 3DS url bilgisi.
success	Banka 3D acs işlem sonuç bilgisi.
message	İşlem cevap açıklaması.
code	İşlem cevap kodu.
bankTransactionId	Banka Transaction ID değeri.
orderId	Ödemeye ait sipariş numarası.
htmlForm	Banka acs form bilgisi.
transactionId	İşleme özel üretilen tekil değer.
sender	OTP’yi ileten issuer banka adı.
durationTimeInSeconds	OTP’nin aktif olma süresi.
otpLength	OTP uzunluğu
gsmNo	OTP’nin iletildiği telefon numarası.
otpRefNo	Banka tarafından üretilen ve kart sahibine ekranda gösterilen, her SMS’de değişecek random bilgidir.
screen	Bir sonraki önerilen akış.
countryCode	Ülke kodu.
emailAddress	Son kullanıcının mail adresi.
channel	OTP doğrulamanın yapıldığı kanal bilgisi. I-Issuer
timestamp	İşlem tarih-saat bilgisi.
error(object)	Hatalı response durumunda doldurulan nesne.
title	Hata başlığı.
code	Hata kodu.
message	Hatanın son kullanıcıya gösterilecek açıklaması.
technicalMessage	Hatanın teknik açıklaması.

Response Davranışı

Ekran Yönlendirme : Response içinde yer alan screen alanı, kullanıcıya gösterilmesi gereken bir sonraki ekranı belirtir. Bu alan BEX tarafından önerilen akış yönlendirmesini temsil eder.

Örnek Başarılı OTP Response

{
  "data": {
    "transactionId": "e55937bd-a2c8-4532-bd42-882a51d74f4c",
    "sender": "ZİRAAT BANKASI",
    "durationTimeInSeconds": 60,
    "otpLength": 6,
    "gsmNo": "5555555555",
    "otpRefNo": "XI010GO6L3",
    "screen": "EnterOtpScreen",
    "countryCode": "90",
    "channel": "I",
    "timestamp": 20260405-23:23:48
  }
}

Response içerisinde “screen” alanı "EnterOtpScreen" olarak döndüğünde akış OTP doğrulama ekranına yönlendirilmelidir. Yine aynı response içerisinde yer alan “transactionId” ve “refNo” değerleri bir sonraki adımda çağırılacak VerifyOTP servisi için kullanılacaktır. Servis detaylarına VerifyOTP sayfasından erişebilirsiniz.

Örnek Başarılı 3D Response

{
  "data": {
    "tdsUrl": "https://setmpos.ykb.com/3DSWebService/YKBPaymentService",
    "success": true,
    "message": "VposPaymentTDSFormSuccess",
    "code": "8000",
    "bankTransactionId": null,
    "orderId": "YKB_0000000010387525",
    "htmlForm": "<form name=\"bkmForm\" action=\"https://setmpos.ykb.com/3DSWebService/YKBPaymentService\" role=\"form\" method=\"POST\"><input type=\"hidden\" name=\"posnetData\" value=\"28FABAD2E4DFB0DD69F67F6CCBFAC0567D508D6B47EA41E288C459D3C8601E3D938F9206816C77D7C1EF23CA5ECBE577EB04135A4409D14A38C70B57826233AB88429B962C8049D4D9BE7B236A4B05C979C298F0A872A227C6D462DE2999F59F91F9D73A7C79928EF997995C32C61D479193554BB0748DFAE3DC5ACA8855A4C15F49F69510317F87A14E0772F6EA74D6F34185FF9300C05ADE527E504D5760117D011BC0DB01A629B24A2E002E31C9AE8520EC429BB5DCFF7AACCDA0EAE35DEBE5B4DDFA43304082A45965F9EA0EAD9C70BC93CC43148A14B414B2393A4EDDF62CC33D1A2D1C6B8250AC07D135236503485C8C39BA24E59BE121191AC80A632135CC53D8B32598FEE78FAA25AD95E5C03FE83A54351C7EA290455B9B7209AE02C437E1CDF8A6CFC88223C4238378E674AA4FB8160F451EE18A35D49B82F50659192080E4AA76E4B8E439CABBA6306C36BC0FE7F25CE0EB4DF47ABD98B430AAF3C318B01EF7412BE6C2F61913C898705D603BC152C42F402B4ED982A44171FF36803C7100BDCB47C57405121718C5F51E2CE0F84A2E11C94E1540FDD67387CD9854675E8B3026C2889CA2B96E9B81008236115747BFB7596C19F1AEA59464B0BC9C71A1A43C7E527AE1DEA39A0ED5AA0FB8FC3E08782B0FD85325946E3A4DA51915FFD2EE646460AFB9ABB2B1\"><input type=\"hidden\" name=\"posnetData2\" value=\"6322A682D2F2F13BB9FBE05BE278614E3B1E7987B95810C8945719D0F714149431C324E79F2AE3B43EAD7A5E0DEF80C8047E8FF8031E48DE21E8FD87EBD1F4A0424B168443DF0675235F4E21B065F7CFD85B0
  }
}

İşlem Kontrol Akışı

Transaction Control servisi ödeme sonucunun SDK tarafında görüntülenmesini sağlayan senkronizasyon servisidir. Verify OTP veya 3D Secure doğrulaması başarılı olduktan sonra işlemin finansallaşması için Merchant backend BEX backend’e ödemeyi tamamlama (Complete Payment) sürecini yürütür. Ödeme işlem sonucu backend to backend olarak Merchant backend’e iletilir. Transanction Control servisi bu sonucun SDK tarafında da görüntülenmesini sağlar.

{
  "data": {
    "paymentToken": "MTextve3TW54CFDWDsc…",
    "screen": "TransactionControlScreen"
  }
}

OTP doğrulama başarılı olduğunda response içerisinde “screen” alanı "TransactionControlScreen" olarak döndüğünde akış bir sonraki adımda Transaction Control servisine yönlendirilmelidir. Yine aynı response içerisinde yer alan “paymentToken” değeri ile ilgili servis çağırılmalıdır.

Örnek Transaction Control Request

GET https://bexmerchant-dev.bkmtest.com.tr/sdk/transaction/control/NjI2NDQ2NmItNTZjZC00NzUwLWE4YTMtOTNhODc2NzA5ZDdi

Örnek Başarılı Response

{
  "data": {
    "posResponseMessage": "VposPaymentSuccess",
    "successAmount": 202.0,
    "authCode": "354075",
    "hostRefCode": "345235407590000261",
    "procReturnCode": null,
    "secureType": 10.0,
    "transactionType": 10.0,
    "installment": 1.0,
    "terminalInformation": null,
    "cardBrand": 10.0,
    "cardType": 0.0,
    "cardNumber": "450634******1809",
    "bankTransactionDate": "2026-04-03T16:01:13.922419+03:00",
    "transactionDate": "2026-04-03T15:57:41.799",
    "paymentId": 0.0,
    "hostRefNum": null,
    "success": true,
    "message": "VposPaymentSuccess",
    "code": "7000",
    "bankTransactionId": "345235407590000261",
    "orderId": "BKM_00000000000010387508"
  }
}

Start Payment with Registered Card

Kullanıcının yeni kart girerek ödeme başlatmasını sağlar. Kart doğrulama sonrası BEX havuzuna kaydedilir; güvenlik tipi, 3D callback, POS yönlendirme, hash kuralları ve orderId kuralları Start Payment ile aynı mantıkta çalışır.

Bu Akışın Farkı

Kart datası SDK içinde PCI-DSS kurallarına uyumlu şekilde şifrelenir. Şifrelenmiş veri tokenizedPan alanı ile ödeme servisine iletilir.
Ödeme akışı sırasında 3D Secure veya OTP doğrulaması gerçekleşirse, kart otomatik olarak BEX hesabına kaydedilir.
Başarılı ödeme sonrası kart ilgili BEX hesabı ile ilişkilendirilir ve sonraki işlemlerde kayıtlı kart olarak kullanılabilir.

Bu servis ödeme akışı, doğrulama adımları, response yönetimi ve finansallaştırma süreçleri açısından Start Payment servisi ile birebir aynıdır. Servis detayları ve iş kuralları için Start Payment sayfasını referans alabilirsiniz.

Sözleşmeler ve Kullanıcı Onayı

Kart kaydederek ödeme akışında kullanıcıya gösterilmesi gereken sözleşme ve onay bilgileri BEX tarafından döndürülür. SDK Initialization yapıldıktan sonra onay bekleyen sözleşmeler response içerisinde pendingAgreements ve ilgili açıklama alanları ile iletilir. Bu sözleşmeler için kullanıcı onayı SDK tarafından sağlanan checkbox komponenti ile alınmalıdır.

Response içerisinde type alanı "AGREEMENT" olarak döndüğünde UI’da checkbox gösterilmelidir.

Response içerisinde type alanı “INFO” olarak döndüğünde (örneğin KVKK) içerik kullanıcıya bilgilendirme metni olarak gösterilmeli checkbox onayının bir parçası olmamalıdır.

pendingAgreements Response Parametereleri

Parametre	Açıklama
id	Sözleşme Id'si
code	Sözleşme Kodu KVKK → KVKK TERMS_OF_USE → Kullanıcı Sözleşmesi MARKETING → Ticari Elektronik İleti İzni
type	Sözleşme Tipi (checkbox çıkmasını belirler) AGREEMENT → checkbox yer alır. (Örn: Kullanıcı Sözleşmesi, Ticari Elektronik İleti İzni) INFO → checkbox yer almaz. (Örn: KVKK)
contentType	Gösterim için içerik tipi HTML URL
title	Sözleşmenin gösterileceği sayfada kullanılacak olan başlık bilgisi
content	Sözleşme Metinleri (URL ise URL bilgisi, raw html ise raw html değeri)
labelHighlight	Sözleşme onayı için gösterilen metinde highlight edilmesi beklenen kelime veya kelime grubunu iletir. Örn: "Kullanıcı Sözleşmesini okudum, onaylıyorum." cümlesi için labelHighlight parametre değeri olarak "Kullanıcı Sözleşmesi" iletilebilir.
label	Sözleşme onayı için gösterilen metin. Örn: "Kullanıcı Sözleşmesini okudum, onaylıyorum."
mandatory	Onay ve gösterim zorunlu mu? true / false Kullanıcı sözleşmesi ve KVKK için true Ticari Elektronik İleti İzni için false

Örnek pendingAgreements Response:

{
 "pendingAgreements": [
 {
 "id": 1,
 "code": "TERMS_OF_USE",
 "type": "AGREEMENT",
 "contentType": "HTML",
 "title": "Kullanıcı Sözleşmesi",
 "content": "<p>Kullanım Koşulları ...</p>",
 "labelHighlight": "Kullanıcı Sözleşmesi",
 "label": "Kullanıcı Sözleşmesini onaylıyorum.",
 "mandatory": true
 },
 {
 "id": 2,
 "code": "KVKK",
 "type": "INFO",
 "contentType": "URL",
 "title": "BKM EXPRESS KVKK Aydınlatma Metni",
 "content": "https://bkmexpress.com.tr/KVKK",
 "labelHighlight": "",
 "label": "",
 "mandatory": true
 }
 ]
}

Zorunlu sözleşmeler onaylanmadığı takdirde MISSED_MANDATORY_AGREEMENT hatası alınacaktır.

Complete Payment

Complete Payment, Start Payment veya Start Payment with Card Registration çağrıları sonrasında doğrulama adımı başarıyla tamamlandığında merchant backend tarafından tetiklenir. Bu servis bankaya finansal talebi iletir ve işlemin gerçek otorizasyon / finansallaşma sonucu burada alınır.

İş Kuralları

Bu servis yalnızca merchant backend tarafından çağrılmalıdır.
Client SDK veya client uygulama Complete Payment servisini doğrudan çağırmamalıdır.
Complete Payment çağrısı için gerekli transactionId, daha önce başlatılmış ve başarıyla doğrulanmış bir ödeme akışından gelmelidir.
OTP veya 3D doğrulama tamamlanmadan Complete Payment çağrısı yapılmamalıdır.
3D challenge sonucu kullanıcı tarafında başarılı görünse bile finansal sonuç yalnızca Complete Payment response’u ile kesinleşir.
Merchant backend, callback veya polling ile doğrulama tamamlandığını teyit ettikten sonra Complete Payment çağrısını başlatmalıdır.
Aynı transactionToken ile tekrar eden completion çağrıları için sistem idempotent davranış gösterebilir veya duplicate completion hatası üretebilir.
Servis IP secure çalışır; erişim izni network seviyesinde yalnızca önceden tanımlanmış sabit IP adresleri için verilir.
Tanımlı IP bilgilerinde değişiklik olacaksa, erişim kesintisi yaşanmaması için değişiklik öncesi Dijital Entegrasyon ekibine bilgi vermelidir.

Request Parametereleri

Parametre	Tip	Zorunlu	Kısıtlar	Açıklama
merchantId	string	Required	Max: 36	Bex tarafından üretilen merchant unique değeri. (bu bilgi bex ekibi tarafından oluşturulup üye işyeri ile paylaşılacaktır).
gsmNo	string	Required	Max: 10	Son kullanıcı telefon numarası.
merchantUserId	string	Required	Max: 255	Merchant tarafından üretilen son kullanıcıya ait tekil değer.
transactionId	string	Required	Max: 36	Her işlem özelinde üretilmesi beklenen benzersiz değer.
amount	double	Required		Ödemenin tutar bilgisi Format: 12.00 12.54 122345.34
transactionDate	string	Required		Tarih-saat bilgisi. ISO 8601 Format: YYYY-MM-DDTHH:mm:ss.sssZ
orderId	string	Required	Max: 255	Ödeme işlemine ait sipariş numarası.
installmentCount	number	Required	Max: 2	Taksit bilgisi. Tek çekim işlemlerde “1” gönderilmelidir.

Endpoint

POST https://bexmerchant-dev.bkmtest.com.tr/merchant/sdk/transaction/completepayment

Örnek Request

curl -X POST \
  https://bexmerchant-dev.bkmtest.com.tr/merchant/sdk/transaction/completepayment \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 72275e90-28ee-4df2-a3bb-79d3d92adfe1,562ace3b-a4ab-4620-98eb-9e3e70e7855d' \
  -H 'accept: */*' \
  -H 'cache-control: no-cache,no-cache' \
  -d '{
    "amount": 202.5,
    "currency": "TRY",
    "installmentCount": 1,
    "merchantId": "11111111-1111-1111-1111-111111111114",
    "gsmNo": "5052148528",
    "merchantUserId": "113355771",
    "orderId": "adfasdfl",
    "transactionId": "a19127c2-aea8-436b-8d71-eefd43e82ae9",
    "transactionDate": "2026-04-06T23:23:09.507+03:00"
}'

Response Parametereleri

Parametre	Açıklama
data(object)	Başarılı response durumunda doldurulan nesne.
posResponseMessage	Bearer olarak kullanılacak token değeri.
successAmount	İşyeri ismi.
authCode	Banka Auth Code değeri.
hostRefCode	Banka HostMsg değeri.
procReturnCode	Banka Sonuç Kod değeri.
secureType	İşlem güvenlik tipi.
transactionType	İşlem tipi.
installment	İşlem taksit sayısı.
terminalInformation	İşlem terminal bilgileri.
cardBrand	Kartın markası(TROY/VISA/MASTERCARD)
cardType	Kart tipi (Debit/Credit).
cardNumber	Maskeli kart numarası.
bankTransactionDate	İşlemin banka transaction tarihi.
transactionDate	İşlem tarihi.
paymentId	İşlem bilgi numarası.
hostRefNum	İşlem banka referans numarası.
success	İşlem sonucu.
message	İşlem cevap açıklaması.
code	İşlem cevap kodu.
bankTransactionId	Banka Transaction ID değeri.
orderId	İşlem sipariş numarası.

Örnek Başarılı Response

{
  "data": {
    "posResponseMessage": "VposPaymentSuccess",
    "successAmount": 202.0,
    "authCode": "354075",
    "hostRefCode": "345235407590000261",
    "procReturnCode": null,
    "secureType": 10.0,
    "transactionType": 10.0,
    "installment": 1.0,
    "terminalInformation": null,
    "cardBrand": 10.0,
    "cardType": 0.0,
    "cardNumber": "450634******1809",
    "bankTransactionDate": "2026-04-03T16:01:13.922419+03:00",
    "transactionDate": "2026-04-03T15:57:41.799",
    "paymentId": 0.0,
    "hostRefNum": null,
    "success": true,
    "message": "VposPaymentSuccess",
    "code": "7000",
    "bankTransactionId": "345235407590000261",
    "orderId": "BKM_00000000000010387508"
  }
}

SDK Initialization​

Lifecycle Kuralları

Generate Token​

CheckStatus​

LinkAccount​

StoreCard​

VerifyOTP​

ResendOTP​

CardDelete​

Start Payment​

Güvenlik Modeli

Varsayılan Davranış

İstek Bazlı Yönlendirme

Yönlendirme Stratejisi

Varsayılan Yönlendirme

İstek Bazlı Yönlendirme

Sipariş Yönetimi

Otomatik Mod

Manuel Mod

Hash Yönetimi

Varsayılan Davranış

İsteğe Bağlı Doğrulama

Start Payment with Registered Card​

Complete Payment​

SDK Initialization

Generate Token

CheckStatus

LinkAccount

StoreCard

VerifyOTP

ResendOTP

CardDelete

Start Payment

Start Payment with Registered Card

Complete Payment