# Ödeme İşlemleri

Ödeme endpoint'leri araç kiralama siparişleri için eksiksiz ödeme işleme iş akışını ele alır. Sistem, 3D Secure kimlik
doğrulamalı kredi kartı ödemeleri ve onaylı acenteler için kredi limiti ödemeleri dahil olmak üzere birden fazla ödeme
yöntemini destekler.

## Taksit Bilgilerini Al

Kartın BIN numarasına ve sipariş tutarına göre kredi kartı ödemeleri için mevcut taksit seçeneklerini alın. Bu endpoint,
müşterilerin satın almalarını tamamlamadan önce ödeme seçeneklerini anlamalarına yardımcı olur.

### Endpoint

```
POST /payment/installment-info
```

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin:

```
Authorization: Bearer ERIŞIM_JETONUNUZ
```

### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `orderID` | string | Evet | Taksit hesaplanacak sipariş kimliği |
| `binNumber` | string | Evet | Kredi kartı numarasının ilk 6 hanesi |


### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/payment/installment-info \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -d '{
    "orderID": "order_123456789",
    "binNumber": "543210"
  }'
```

### Yanıt

**Başarılı Yanıt (200 OK):**

```json
{
  "bankCode": 12,
  "bankName": "Örnek Banka",
  "binNumber": "543210",
  "cardAssociation": "MasterCard",
  "cardFamily": "World",
  "cardType": "credit",
  "shouldForceTo3D": true,
  "supportedCurrencies": [
    "TRY",
    "USD",
    "EUR"
  ],
  "installmentPrices": [
    {
      "number": 1,
      "price": {
        "amount": 54500,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 54500,
        "currency": "TRY"
      }
    },
    {
      "number": 3,
      "price": {
        "amount": 18500,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 55500,
        "currency": "TRY"
      }
    },
    {
      "number": 6,
      "price": {
        "amount": 9500,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 57000,
        "currency": "TRY"
      }
    },
    {
      "number": 12,
      "price": {
        "amount": 5000,
        "currency": "TRY"
      },
      "totalPrice": {
        "amount": 60000,
        "currency": "TRY"
      }
    }
  ]
}
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `bankCode` | integer | Banka tanımlayıcı kodu |
| `bankName` | string | Banka adı |
| `binNumber` | string | Sorgu için kullanılan BIN numarası |
| `cardAssociation` | string | Kart ağı (Visa, MasterCard, vb.) |
| `cardFamily` | string | Kart ailesi (Classic, Gold, Platinum, vb.) |
| `cardType` | string | Kart türü (credit, debit) |
| `shouldForceTo3D` | boolean | Bu kart için 3D Secure zorunlu mu |
| `supportedCurrencies` | array | Kart tarafından desteklenen para birimleri |
| `installmentPrices` | array | Mevcut taksit seçenekleri |
| `installmentPrices[].number` | integer | Taksit sayısı |
| `installmentPrices[].price` | object | Aylık ödeme tutarı |
| `installmentPrices[].totalPrice` | object | Faizli toplam tutar |


## Ödeme İşle

Kredi kartı veya kredi limiti kullanarak sipariş için ödeme işleyin. Bu endpoint hem 2D hem de 3D Secure kredi kartı
ödemelerini ve onaylı acenteler için kredi limiti ödemelerini ele alır.

### Endpoint

```
POST /payment/pay
```

### Kimlik Doğrulama

Bu endpoint kimlik doğrulama gerektirir. Authorization başlığında JWT erişim jetonunuzu ekleyin.

### Test Ortamı Ödeme Kuralları

Test ortamında ödeme kuralları farklıdır:

- Test ortamında ödemeler yalnızca `Yolcutest` tedarikçisi için desteklenmektedir.
- Bu kurala takılan ödemeler şu şekilde yanıtlanır:
  - `code`: `6008`
  - `description`: `Payments in the staging environment are only supported for the "Yolcutest" vendor.`


### İstek Gövdesi

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `orderID` | string | Evet | Ödeme işlenecek sipariş kimliği |
| `paymentType` | string | Evet | Ödeme yöntemi: `creditCard` veya `limit` |
| `payWithCard` | object | Koşullu | Kredi kartı detayları (paymentType creditCard ise gerekli) |


#### Kredi Kartı Ödemesi (`payWithCard`)

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `cardNumber` | string | Evet | Kredi kartı numarası (PCI uyumlu işleme) |
| `expireMonth` | string | Evet | Kart son kullanma ayı (01-12) |
| `expireYear` | string | Evet | Kart son kullanma yılı (YYYY) |
| `cardHolderName` | string | Evet | Kartta yazılı ad |
| `cvc` | string | Evet | 3 haneli güvenlik kodu |
| `installment` | integer | Evet | Taksit sayısı (tek ödeme için 1) |
| `isWith3DSecure` | boolean | Evet | 3D Secure kimlik doğrulaması kullanılsın mı |
| `callbackUrl` | string | Evet | 3D Secure tamamlama callback URL'i |


### Örnek İstekler

#### Kredi Kartı Ödemesi

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/payment/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -d '{
    "orderID": "order_123456789",
    "paymentType": "creditCard",
    "payWithCard": {
      "cardNumber": "4242424242424242",
      "expireMonth": "12",
      "expireYear": "2025",
      "cardHolderName": "Ahmet Yılmaz",
      "cvc": "123",
      "installment": 3,
      "isWith3DSecure": true,
      "callbackUrl": "https://siteniz.com/payment/callback"
    }
  }'
```

#### Kredi Limiti Ödemesi

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/payment/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ERIŞIM_JETONUNUZ" \
  -d '{
    "orderID": "order_123456789",
    "paymentType": "limit"
  }'
```

### Yanıt

#### 2D Ödeme Başarısı (200 OK)

```json
{
  "status": "success",
  "is3dsSecure": false,
  "threeDSHtmlContent": null
}
```

#### 3D Secure Gerekli (200 OK)

```json
{
  "status": "redirect_required",
  "is3dsSecure": true,
  "threeDSHtmlContent": "<!DOCTYPE html><html><head><title>3D Secure</title></head><body><form id='threeDSForm' action='https://3ds.bank.com/auth' method='POST'>...</form><script>document.getElementById('threeDSForm').submit();</script></body></html>"
}
```

#### Kredi Limiti Ödeme Başarısı (200 OK)

```json
{
  "status": "success",
  "is3dsSecure": false,
  "threeDSHtmlContent": null
}
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `status` | string | Ödeme durumu (success, redirect_required, failed) |
| `is3dsSecure` | boolean | Ödeme 3D Secure kimlik doğrulaması gerektiriyor mu |
| `threeDSHtmlContent` | string | 3D Secure yönlendirmesi için HTML içeriği (gerekirse) |


## 3D Secure Callback

Müşteri banka ile kimlik doğrulamasını tamamladıktan sonra 3D Secure kimlik doğrulama callback'ini ele alın. Bu endpoint
ödeme işlemcisi tarafından otomatik olarak çağrılır.

### Endpoint

```
POST /payment/3ds-callback/{orderID}
```

### Yol Parametreleri

| Parametre | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `orderID` | string | Evet | İşlenen ödeme için sipariş kimliği |


### İstek Gövdesi (Form Data)

| Alan | Tür | Gerekli | Açıklama |
|  --- | --- | --- | --- |
| `language` | string | Evet | Yanıt için dil kodu |
| `paymentId` | string | Evet | Ödeme işlem kimliği |
| `transactionId` | string | Evet | Banka işlem kimliği |


### Örnek İstek

```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/payment/3ds-callback/order_123456789 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'language=tr&paymentId=payment_123456&transactionId=txn_789012'
```

### Yanıt

**Başarılı Yanıt (200 OK):**

Kullanıcıyı ödeme sonucuyla birlikte uygulamanıza yönlendiren HTML içeriği döndürür.

```html
<!DOCTYPE html>
<html>
<head>
    <title>Ödeme Tamamlandı</title>
</head>
<body>
<script>
    window.location.href = 'https://siteniz.com/payment/success?orderID=order_123456789&status=success';
</script>
</body>
</html>
```

## Ödeme Yöntemleri

### Kredi Kartı Ödemeleri

#### Desteklenen Özellikler

- **Kart Türleri**: Visa, MasterCard, American Express
- **3D Secure**: Kart ve tutara göre isteğe bağlı veya zorunlu
- **Taksitler**: Kart türüne göre birden fazla taksit seçeneği
- **Para Birimleri**: TRY, USD, EUR (kart desteğine bağlı)


#### 3D Secure Akışı

1. Müşteri 3D Secure etkin ödeme gönderir
2. API banka kimlik doğrulaması için HTML içeriği döndürür
3. Müşteri bankanın web sitesinde kimlik doğrulamasını tamamlar
4. Banka 3D Secure callback endpoint'ine yönlendirir
5. Ödeme sonuçlandırılır ve müşteri başarı sayfasına yönlendirilir


#### Güvenlik Özellikleri

- **PCI Uyumluluğu**: Tüm kart verileri güvenli şekilde işlenir
- **Tokenizasyon**: Kart numaraları hiçbir zaman düz metin olarak saklanmaz
- **SSL/TLS**: Tüm iletişimler şifrelenir
- **Fraud Algılama**: Yerleşik sahtekarlık koruma mekanizmaları


### Kredi Limiti Ödemeleri

#### Uygunluk

- Onaylı kredi limitli acenteler için mevcuttur
- Aktif kredi sözleşmesi gerektirir
- Mevcut kredi bakiyesine tabidir


#### İşleme

- Anında ödeme işleme
- Ek kimlik doğrulama gerekmez
- Otomatik kredi limiti ayarlaması
- Kredi koşullarına göre faturalama gerçekleşir


## Ödeme En İyi Uygulamaları

### Kredi Kartı İşleme

- **BIN Doğrulama**: Ödemeden önce her zaman taksit seçeneklerini kontrol edin
- **3D Secure**: Gelişmiş güvenlik için 3D Secure kullanın
- **Hata İşleme**: Ödeme başarısızlıkları için sağlam hata işleme uygulayın
- **Zaman Aşımı Yönetimi**: Ödeme zaman aşımlarını zarif şekilde ele alın


### Güvenlik Değerlendirmeleri

- **PCI Uyumluluğu**: Entegrasyonunuzun PCI DSS gereksinimlerini karşıladığından emin olun
- **Veri Koruması**: Hassas kart bilgilerini hiçbir zaman günlüklemeyin veya saklamayın
- **Yalnızca HTTPS**: Ödeme iletişimleri için her zaman HTTPS kullanın
- **Token Yönetimi**: Ödeme tokenlerini ve callback'leri güvenli şekilde işleyin


### Kullanıcı Deneyimi

- **İlerleme Göstergeleri**: Kullanıcılara net ödeme ilerlemesi gösterin
- **Hata Mesajları**: Başarısız ödemeler için yardımcı hata mesajları sağlayın
- **Yeniden Deneme Mantığı**: Kullanıcıların başarısız ödemeleri yeniden denemesine izin verin
- **Onay**: Kullanıcılara her zaman ödeme onayı gösterin


## Ödeme İş Akışı

### Kredi Kartı Ödeme Akışı

```mermaid
graph TD
    A[Sipariş Oluştur] --> B[Taksit Bilgilerini Al]
    B --> C[Ödeme Gönder]
    C --> D{3D Secure Gerekli?}
    D -->|Hayır| E[Ödeme Başarısı]
    D -->|Evet| F[Bankaya Yönlendir]
    F --> G[Müşteri Kimlik Doğrulaması]
    G --> H[3D Secure Callback]
    H --> I{Kimlik Doğrulama Başarılı?}
    I -->|Evet| E
    I -->|Hayır| J[Ödeme Başarısız]
    E --> K[Sipariş Tamamlandı]
    J --> L[Ödemeyi Yeniden Dene]
    L --> C
```

### Kredi Limiti Ödeme Akışı

```mermaid
graph TD
    A[Sipariş Oluştur] --> B[Kredi Limitini Kontrol Et]
    B --> C{Yeterli Kredi?}
    C -->|Evet| D[Ödemeyi İşle]
    C -->|Hayır| E[Yetersiz Kredi]
    D --> F[Ödeme Başarısı]
    F --> G[Kredi Bakiyesini Güncelle]
    G --> H[Sipariş Tamamlandı]
    E --> I[Alternatif Ödeme Kullan]
```

## Hata İşleme

### Yaygın Hata Yanıtları

- `400 Bad Request`: Geçersiz ödeme verisi veya eksik gerekli alanlar
- `401 Unauthorized`: Kimlik doğrulama gerekli veya jetonun süresi dolmuş
- `402 Payment Required`: Yetersiz kredi limiti veya kart reddedildi
- `404 Not Found`: Sipariş bulunamadı veya ödeme zaten işlendi
- `422 Unprocessable Entity`: Ödeme doğrulama hataları
- `500 Internal Server Error`: Ödeme işlemcisi hatası


### Örnek Hata Yanıtı

```json
{
  "code": 2001,
  "description": "Kredi kartı reddedildi",
  "details": {
    "field": "cardNumber",
    "message": "Kart banka tarafından reddedildi",
    "bankCode": "05",
    "bankMessage": "İşlemi onaylamayın"
  }
}
```

### Ödeme Hata Kodları

| Kod | Açıklama | Eylem |
|  --- | --- | --- |
| 2001 | Kart reddedildi | Farklı kart veya ödeme yöntemi deneyin |
| 2002 | Yetersiz bakiye | Kart bakiyesini kontrol edin veya farklı kart kullanın |
| 2003 | Kartın süresi dolmuş | Kart son kullanma tarihini güncelleyin |
| 2004 | Geçersiz kart numarası | Kart numarasının doğru olduğunu doğrulayın |
| 2005 | Geçersiz CVC | Güvenlik kodunu kontrol edin |
| 2006 | 3D Secure başarısız | Doğru kimlik doğrulamasıyla yeniden deneyin |
| 2007 | Kredi limiti aşıldı | Alternatif ödeme yöntemi kullanın |
| 2008 | Ödeme zaman aşımı | Ödemeyi yeniden deneyin |
| 6008 | Test ortamı tedarikçi kontrolü | Test ortamında Yolcutest tedarikçisini kullanın |


## Entegrasyon Örnekleri

### Eksiksiz Ödeme Akışı

```javascript
// Adım 1: Taksit seçeneklerini al
async function getInstallmentOptions(orderID, cardNumber) {
    const binNumber = cardNumber.substring(0, 6);

    const response = await fetch('/api/v1/payment/installment-info', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify({
            orderID: orderID,
            binNumber: binNumber
        })
    });

    return await response.json();
}

// Adım 2: Ödemeyi işle
async function processPayment(orderID, cardDetails, installmentOption) {
    const paymentData = {
        orderID: orderID,
        paymentType: 'creditCard',
        payWithCard: {
            cardNumber: cardDetails.number,
            expireMonth: cardDetails.expireMonth,
            expireYear: cardDetails.expireYear,
            cardHolderName: cardDetails.holderName,
            cvc: cardDetails.cvc,
            installment: installmentOption.number,
            isWith3DSecure: true,
            callbackUrl: `${window.location.origin}/payment/callback`
        }
    };

    const response = await fetch('/api/v1/payment/pay', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify(paymentData)
    });

    const result = await response.json();

    if (result.is3dsSecure) {
        // 3D Secure yönlendirmesini ele al
        document.body.innerHTML = result.threeDSHtmlContent;
    } else {
        // 3D Secure olmadan ödeme tamamlandı
        handlePaymentSuccess(result);
    }
}

// Adım 3: 3D Secure callback'ini ele al
function handle3DSCallback() {
    const urlParams = new URLSearchParams(window.location.search);
    const orderID = urlParams.get('orderID');
    const status = urlParams.get('status');

    if (status === 'success') {
        handlePaymentSuccess();
    } else {
        handlePaymentFailure();
    }
}
```

### Kredi Limiti Ödemesi

```javascript
async function processCreditLimitPayment(orderID) {
    const response = await fetch('/api/v1/payment/pay', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`
        },
        body: JSON.stringify({
            orderID: orderID,
            paymentType: 'limit'
        })
    });

    if (!response.ok) {
        const error = await response.json();
        throw new Error(`Ödeme başarısız: ${error.description}`);
    }

    return await response.json();
}
```

## Hız Sınırlama

Ödeme endpoint'leri hız sınırlamasına tabidir:

- **Taksit bilgisi**: Kullanıcı başına dakikada maksimum 30 istek
- **Ödeme işle**: Kullanıcı başına dakikada maksimum 10 istek
- **3D Secure callback**: Sipariş başına dakikada maksimum 100 istek


Uygun yeniden deneme mantığını uygulayın ve yanıtlarda hız sınırı başlıklarını izleyin.