🧾 Ödeme Almak

🔐 1. Token Oluşturmak

Endpoint

GET /api/cardPayment/token

Açıklama

Güvenlik amaçlı token üretir. Diğer işlemler öncesinde bu token kullanılır. Ödeme almanın ilk adımı tek seferlik güvenlik tokeni oluşturmaktır.

Response: PrepareToken

{
  "token": "string"
}

Notlar

• Token her işlem için tek kullanımlıktır.
• Token süresi sınırlıdır, 5 dakika içinde kullanılmalıdır.

---

🛠 2. Kart Ödemesine Hazırlık

Endpoint

POST /api/cardPayment/prepare

Açıklama

Kart bilgilerinin ön doğrulaması yapılır. Asıl ödeme işlemi bu adımdan sonra başlatılır.

Request: PrepareCardPaymentRequest

{
  "creditCard": {
    "cardNumber": "string",
    "cvv": "string",
    "expireMonth": 1,
    "expireYear": 2025,
    "cardHolderName": "string"
  }
}

Response: HTTP 200 OK

(Başarılıysa tekrar bu istek döner. Aksi halde ProblemDetails döner.)

İpucu

• Bu adım fraud kontrolü ve BIN analizi gibi işlemler için kullanılır.

---

💸 3. Kart Ödemesi

Endpoint

POST /api/cardPayment

Açıklama

Karttan ödeme işlemi yapılır. 3D Secure desteklidir.

Request: CardPaymentRequest

{
  "token": "string",
  "amount": 1.0,
  "installment": 1,
  "referenceCode": "unique-ref-123",
  "card": {
    "cardNumber": "string",
    "cvv": "string",
    "expireMonth": 12,
    "expireYear": 2025,
    "cardHolderName": "string"
  },
  "useStoredCard": false,
  "ownerKey": "string",
  "cardId": "uuid",
  "saveCard": false,
  "customerIp": "string",
  "reward": {
    "amount": 1.0,
    "useReward": true
  },
  "invoice": { ... },
  "shipping": { ... },
  "explanation": "Açıklama",
  "use3d": true,
  "additionalData": {
    "property1": "extra1"
  },
  "currency": "TRY",
  "email": "user@example.com",
  "phone": "5551234567",
  "returnURL": "https://example.com/return",
  "chargeType": "directSale",
  "paymentSystemId": "UUID",
  "nationalNumber": "12345678901",
  "products": [
    {
      "id": "prod-1",
      "category": "electronics",
      "quantity": 1,
      "code": "PRD001",
      "description": "Product desc",
      "price": 1.0
    }
  ]
}

Notlar

• referenceCode her işlem için eşsiz olmalıdır.
• use3d true ise kullanıcı 3D Secure sayfasına yönlendirilir.
• chargeType: "directSale" ya da "provision" olabilir.
• additionalData Bankalara gönderilecek banka özelinde değerler için kullanılır.
• Kayıtlı kart ile ödeme yapılmak istenirse, cardId, ownerKey, useStoredCard:true gönderilmesi gerekmektedir. Bu bilgiler kart kaydı yapıldığında webhook ile size iletilen bilgilerdir.
• Kartı ödeme sonrasında kaydetmek için saveCard:true gönderilmelidir

---

🧾 4. Provizyon İşleminin Tamamlanması

Endpoint

POST /api/cardPayment/provisionCommit

Açıklama

Ön provizyon işlemlerinde bloklanan tutarın gerçekten çekilmesini sağlar.

Request: ProvisionCommitRequest

{
  "referenceCode": "unique-ref-123",
  "amount": 1.0
}

Notlar

• Sadece chargeType = "provision" olan işlemler için geçerlidir.
• Tutar, ilk provizyon tutarından küçük ya da eşit olmalıdır.

---

❌ Ortak Hata Formatı: ProblemDetails

{
  "type": "Error",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key missing or invalid.",
  "instance": "/api/cardPayment"
}

İpucu

• Uygulamada her hata bu standart yapı ile yakalanabilir.

---

📌 Tipler

CardPaymentRequest

Field	Type	Required	Annotations	Allowed Values	Description
token	string	No	-	-	Ham kart bilgisi yerine kullanılan tokenize edilmiş kart değeridir.
amount	float	Yes	required	-	Karttan tahsil edilecek toplam ödeme tutarıdır.
installment	integer	No	-	-	Ödemeye uygulanacak taksit sayısını belirtir.
referenceCode	string	Yes	required	-	İşlemi takip etmek için kullanılan benzersiz üye işyeri referans kodudur.
card	CreditCard	No	-	-	Kayıtlı kart kullanılmıyorsa ödeme için kullanılacak kart bilgileridir.
useStoredCard	bool	No	-	-	Daha önce saklanmış bir kartın kullanılıp kullanılmayacağını belirtir.
ownerKey	string	No	-	-	Kart sahibini veya müşteriyi üye işyeri sisteminde tanımlayan benzersiz anahtardır.
cardId	uuid	No	-	-	İşlemde kullanılacak kayıtlı kartın kimliğidir.
saveCard	bool	No	-	-	Başarılı ödeme sonrası kartın saklanıp saklanmayacağını belirtir.
customerIp	string	No	-	-	İşlemi gerçekleştiren müşterinin IP adresidir.
reward	RewardUsage	No	-	-	Ödeme sırasında kullanılacak ödül veya sadakat puanı bilgileridir.
invoice	Address	No	-	-	Müşteriye ait fatura adresi bilgileridir.
shipping	Address	No	-	-	Müşteriye ait teslimat veya gönderim adresi bilgileridir.
explanation	string	No	max(400)	-	İşleme ait ek açıklama veya not bilgisidir.
use3d	bool	No	-	-	Ödemenin 3D Secure ile işlenip işlenmeyeceğini belirtir.
additionalData	{String:String}	No	-	-	İşlemle birlikte gönderilen ek anahtar-değer verileridir.
currency	string	Yes	required, currency (ISO4217)	-	Ödemenin ISO 4217 formatındaki para birimi kodudur.
email	string	Yes	required	-	Ödeme ile ilişkili müşteri e-posta adresidir.
phone	string	Yes	required	-	Ödeme ile ilişkili müşteri telefon numarasıdır.
returnURL	string	No	url	-	3D Secure veya ödeme tamamlandıktan sonra müşterinin yönlendirileceği URL adresidir.
chargeType	SalesType	No	-	DirectSale, Provision	Gerçekleştirilecek tahsilat işlem tipini belirtir.
paymentSystemId	uuid	No	-	-	Kullanılacak ödeme sistemi, banka veya sanal POS entegrasyonunun kimliğidir.
nationalNumber	string	No	-	-	Kart sahibine veya müşteriye ait ulusal kimlik numarasıdır.
products	Product[]	No	-	-	Ödeme ile ilişkili ürün veya sepet kalemlerinin listesidir.

CreditCard

Field	Type	Required	Annotations	Allowed Values	Description
cardNumber	string	No	-	-	İşlemde kullanılacak kart numarasıdır.
cvv	string	No	-	-	Kart üzerinde yer alan güvenlik kodudur.
expireMonth	integer	No	-	-	Kartın son kullanma ayıdır.
expireYear	integer	No	-	-	Kartın son kullanma yılıdır.
cardHolderName	string	No	-	-	Kart üzerinde yazan kart sahibi adıdır.

RewardUsage

Field	Type	Required	Annotations	Allowed Values	Description
amount	float	No	-	-	Kullanılacak ödül veya sadakat bakiyesi tutarıdır.
useReward	bool	No	-	-	Bu ödeme için ödül kullanımının aktif olup olmadığını belirtir.

Address

Field	Type	Required	Annotations	Allowed Values	Description
name	string	No	-	-	Adresle ilişkili kişinin adıdır.
surname	string	No	-	-	Adresle ilişkili kişinin soyadıdır.
countryCode	string	No	-	-	Adresin ülke kodudur, genellikle ISO formatında beklenir.
city	string	No	-	-	Adresin şehir bilgisidir.
district	string	No	-	-	Adresin ilçe, semt veya bölge bilgisidir.
street1	string	No	-	-	Birincil adres satırıdır.
street2	string	No	-	-	Daire, kat veya ek adres detaylarını içeren ikinci adres satırıdır.
number	string	No	-	-	Bina veya kapı numarası bilgisidir.
postalCode	string	No	-	-	Adresin posta kodudur.
company	string	No	-	-	Varsa adresle ilişkili şirket adıdır.
phone	string	No	-	-	Adres için iletişim telefon numarasıdır.
fax	string	No	-	-	Varsa adresle ilişkili faks numarasıdır.

Product

Field	Type	Required	Annotations	Allowed Values	Description
id	string	No	-	-	Ürün veya sepet kalemine ait benzersiz kimliktir.
category	string	No	-	-	Ürünün okunabilir kategori adıdır.
categoryCode	string	No	-	-	Ürüne ait sistem veya üye işyeri kategori kodudur.
quantity	float	No	-	-	Sepette yer alan ürün miktarını belirtir.
code	string	No	-	-	Üye işyerine özel ürün kodu veya stok kodudur.
description	string	No	-	-	Satın alınan ürün veya hizmetin açıklamasıdır.
price	float	No	-	-	Ürün satırına ait birim fiyat veya toplam fiyat bilgisidir.

📝 Ekstra İpuçları

• Sandbox testleri için test kartları sağlayın (örnek: 4111 1111 1111 1111).
• Rate Limiting uygulanabilir, aşırı istekler throttling ile engellenir.
• Loglama yaparken kart bilgilerini (PAN, CVV) kesinlikle maskeleyin ya da loglamayın.
• 3D Secure işlemleri için returnURL HTTPS olmalıdır.