Kart Kaydet

POST/partner/1.0/card/save

Gerekli scope: payment:sale

Ödeme almadan kart saklar. Aboneliğe geçmeden kart bilgisini almak isteyen akışlar için; ödeme sırasında saklamak istiyorsanız card/pay + saveCard: true yeterlidir.

Kart numarası (PAN) hiçbir zaman bizde durmaz — kart sağlayıcıda tokenize edilir, kayıtta yalnız maskeli numara ve sağlayıcı token'ı tutulur.

Tokenizasyonu yapacak POS sağlayıcısını sunucu seçer: aktif yönlendirme kuralınızın sağlayıcısı, yoksa en eski aktif sağlayıcı. İstekte provider / posProviderId göndermeniz gerekmez; gönderseniz de yok sayılır. Kart, ödemenin gittiği sağlayıcıda saklanır.

Örnek

curl -X POST https://<host>/partner/1.0/card/save \
  -H "X-Api-Key: ..." \
  -H "X-Timestamp: ..." \
  -H "X-Signature: ..." \
  -H "Content-Type: application/json" \
  -d '{
  "cardNumber": "5127541122223332",
  "cardHolderName": "Hakan Test",
  "expiryMonth": "12",
  "expiryYear": "2030",
  "cvv": "000",
  "usage": "POS_PAYMENT",
  "alias": "Şirket kartı",
  "setAsDefault": true
}'

İstek Body

Alan	Tip	Açıklama
`cardNumber`zorunlu	string	Kart numarası. Saklanmaz; tokenize edilir.
`expiryMonth`zorunlu	string	Son kullanma ayı (AA).
`expiryYear`zorunlu	string	Son kullanma yılı (YYYY).
`cardHolderName`	string	Kart üzerindeki ad-soyad. Sağlayıcı isteyebilir; doldurmanız önerilir.
`cvv`	string	Güvenlik kodu. Sağlayıcı tokenizasyonu için iletilir, saklanmaz.
`usage`	enum	Kartın kullanım alanı. Boş bırakılırsa POS_PAYMENT. Varsayılan: `POS_PAYMENT` `POS_PAYMENTWALLET_TOPUPBOTH`
`alias`	string	Kart için hatırlatıcı isim.
`setAsDefault`	boolean	Bu kullanım alanında varsayılan yapılsın mı. Varsayılan: `false`
`customerId`	string	Kart bu MÜŞTERİ adına saklanacaksa müşterinin kullanıcı kimliği. Boş ise kart işletmenize kaydedilir.

Yanıt

Alan	Anlamı
`id`	Kayıtlı kart kimliği. Ödemede `savedCardId`, plan kurmada `savedCardId` olarak bu değeri gönderirsiniz.
`maskedPan`	Maskeli kart numarası. Tam PAN hiçbir uçtan dönmez.
`alias`	Kart için verdiğiniz hatırlatıcı isim.
`cardHolderName`	Kart üzerindeki ad-soyad.
`brand` / `bankName` / `cardType`	Kart markası, bankası ve tipi.
`expiryMonth` / `expiryYear`	Son kullanma ayı (AA) ve yılı (YYYY).
`usage`	Kartın kullanım alanı (`POS_PAYMENT`, `WALLET_TOPUP`, `BOTH`).
`status`	Kart durumu (`ACTIVE`, `EXPIRED`, `REVOKED`, `SUSPENDED`).
`isDefault`	Bu kullanım alanında varsayılan kart mı.
`customerId`	Kart bir müşteri adına saklandıysa o müşterinin kimliği; işletmenizin kendi kartında boş.
`createdDate`	Kaydın oluşturulma tarihi.

Örnek yanıt (content)

{
  "id": "8f2c1d5e-9a41-4c7b-b6a2-3f0e8d9c1a2b",
  "alias": "Şirket kartı",
  "maskedPan": "512754******3332",
  "cardHolderName": "Hakan Test",
  "brand": "MASTERCARD",
  "bankName": "Örnek Bank",
  "cardType": "CREDIT",
  "expiryMonth": "12",
  "expiryYear": "2030",
  "usage": "POS_PAYMENT",
  "status": "ACTIVE",
  "isDefault": true,
  "customerId": null,
  "createdDate": "2026-08-17T10:15:30.000Z"
}

Hatalar

Mesaj anahtarı	HTTP	Neden
`cardNumber.empty`	400	cardNumber boş gönderildi.
`expiryMonth.empty`	400	expiryMonth boş gönderildi.
`expiryYear.empty`	400	expiryYear boş gönderildi.
`pos.provider.not.found`	404	İşletmenizde kart saklamaya uygun aktif bir POS sağlayıcısı yok.

İsteği Dene

Önizleme modu — değerler kod örneklerini günceller, gerçek istek atılmaz.

Mock

cardNumber*expiryMonth*expiryYear*cardHolderNamecvvusagealiassetAsDefaultcustomerId