Kart Saklama

Müşterinizin kartını platformun kasasında saklayabilir, sonraki ödemelerde kart bilgisi istemeden çekim yapabilirsiniz. Kart numarası hiçbir zaman size dönmez; elinizde yalnızca opak bir referans (storedCardToken) bulunur.

⚠️

Kart saklama varsayılan olarak kapalıdır. Panelden Ödeme → Form Ayarları → Kart Saklama ile açmanız gerekir. Kapalıyken kayıt yapılmaz ve kayıtlı kartla çekim reddedilir.

Kavramlar

Kavram	Nedir
`cardUserKey`	Sizin müşteri anahtarınız. Kartlar bu anahtarın altında toplanır. Ödemeyi oluştururken gönderdiğiniz `customerId` (veya açıkça verdiğiniz `cardUserKey`) değeridir.
`storedCardToken`	Kaydedilen kartın kalıcı referansı. Çekimde `cardUserKey` ile birlikte gönderilir.

🚫

storedCardToken, checkout formunun /payments/form/tokenize ucundan dönen cardToken ile aynı şey değildir. O token tek kullanımlıktır ve tek bir ödemeye bağlıdır; bu ise kalıcı kasa referansıdır. Karıştırırsanız çekim StoredCardNotFound ile düşer.

Kart nasıl kaydedilir

Kart, ödeme sırasında kaydedilir — ayrı bir "kartı kaydet" çağrısı yoktur.

Ödemeyi müşteri anahtarıyla oluşturun

POST /payments/intents (veya direct API) çağrısında customerId gönderin. Kart bu anahtarın altına kaydedilecek.

{
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-12345",
  "customerId": "cust_7788"
}

Müşteri kimliğinizden farklı bir kart defteri anahtarı kullanıyorsanız cardUserKey alanını açıkça gönderin; boşsa customerId kullanılır.

Ödemede `cardSave` işaretleyin

Hosted formda alıcı "kartımı kaydet" kutusunu işaretler. Direct API'de card.cardSave: true gönderirsiniz.

Ödeme 3D Secure ile tamamlanır

Kart yalnızca 3D Secure'lu ödemede kaydedilir.

Kart, çekim başarılı olduktan sonra kasaya yazılır

Ödeme reddedilirse veya alıcı 3DS'i yarıda bırakırsa kart kaydedilmez.

Neden 3DS zorunlu? Kaydedilen kartla ileride yapacağınız otomatik çekimlerde (abonelik gibi), kart sahibinin onayına dair kanıt gerekir. Bu kanıt 3D Secure doğrulamasıdır. 2D ödemede cardSave: true gönderirseniz 400 payment.card.save_requires_3ds alırsınız — sessizce yok sayılmaz.

Aynı kart iki kez kaydedilmez

Müşteri aynı kartla defalarca ödeyip her seferinde "kaydet" işaretlese bile tek kayıt oluşur ve aynı storedCardToken döner. Son kullanma tarihi veya kart adı değiştiyse mevcut kayıt tazelenir.

Token'ı nasıl alırsınız

Ödeme yanıtında data.savedCard bloğu döner:

{
  "success": true,
  "data": {
    "id": "pay_01H...",
    "status": 3,
    "savedCard": {
      "storedCardToken": "9f3c1a7e-...",
      "cardUserKey": "cust_7788",
      "maskedNumber": "457332******1234",
      "lastFour": "1234",
      "expireMonth": "12",
      "expireYear": "2030",
      "cardBrand": "VISA",
      "deduplicated": false
    }
  }
}

deduplicated: true ise kart zaten kayıtlıydı ve mevcut token döndü.

Kayıtlı kartla ödeme

cardUserKey ve storedCardToken birlikte gönderilir:

{
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-12346",
  "card": {
    "cardUserKey": "cust_7788",
    "cardToken": "9f3c1a7e-...",
    "cvcNumber": "123"
  }
}

Bankaların çoğu kayıtlı kart çekiminde de CVC ister. Alıcı ekranda değilse (otomatik tahsilat) CVC gönderemezsiniz; bu durumda çekim Subscription üzerinden yapılmalıdır — orada işlem "merchant tarafından başlatıldı" olarak işaretlenir.

Kartları listeleme

GET /payments/cards?cardUserKey=cust_7788

İzin: payment:cards-view

{
  "cards": [
    {
      "storedCardToken": "9f3c1a7e-...",
      "cardUserKey": "cust_7788",
      "cardHolderName": "JOHN DOE",
      "cardName": "İş Bankası kartım",
      "maskedNumber": "457332******1234",
      "lastFour": "1234",
      "expireMonth": "12",
      "expireYear": "2030",
      "cardBrand": "VISA",
      "bankName": "Garanti",
      "createdAt": "2026-01-15T10:22:00.000Z"
    }
  ],
  "total": 1
}

cardUserKey zorunludur. Bir merchant'ın tüm kayıtlı kartlarını topluca döken bir uç bilinçli olarak yoktur.

Tek kart için: GET /payments/cards/{storedCardToken}

Kart silme

DELETE /payments/cards/{storedCardToken}

İzin: payment:cards-manage — okuma izni tek başına yetmez.

⚠️

Bu karta bağlı bir abonelik varsa otomatik tahsilat durur. Silmeden önce müşterinin başka bir kartı olduğundan emin olun.

Silme geri alınamaz: kart bir daha çekilemez ve listede görünmez. Aynı token ikinci kez silinmeye çalışılırsa 404 döner.

Müşteri kartını daha sonra tekrar kaydedebilir; bu yeni bir kayıt olur ve yeni bir token alır.

Süresi geçen kartlar

Son kullanma tarihi geçen kartlar otomatik olarak pasifleştirilir: listede görünmez ve çekilemez. Kart yenilendiğinde müşteri yeniden kaydetmelidir.

Formda kayıtlı kart gösterimi

Hosted checkout formunda alıcı, daha önce kaydettiği kartları görüp seçebilir. Bunun için ödemeyi oluştururken customerId (veya cardUserKey) göndermeniz yeterlidir — form o anahtara ait aktif kartları listeler.

Anahtar göndermezseniz form kart listesi göstermez; kimin kartlarını göstereceğini bilemez.

Güvenlik notları

Kart numarası hiçbir uçtan dönmez; yalnızca maskeli gösterim saklanır ve gösterilir.
cardUserKey hiçbir zaman tarayıcıdan alınmaz — sunucu onu ödeme kaydından çözer. Bu, bir alıcının başkasının kart defterine erişmesini yapısal olarak engeller.
Başka bir merchant'ın token'ıyla yapılan sorgu 404 döner (403 değil) — token'ın varlığı sızdırılmaz.

Birden Fazla Yöntemle Ödeme Ödeme Listeleme