> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Puan Sorgulama

> Bonus, Maximum, World gibi banka programlarının puan bakiyesini sorgulayın.

Türk bankalarının kart programları (Bonus, Maximum, Axess, World, Paraf, Cardfinans, Wings) müşteriye **puan biriktirme** sunar. Bu endpoint, kart bazında puan bakiyesi sorgulamak için kullanılır.

<Note>
  Tüm bankalar puan sorgu API'si sunmaz. Şu anda **HalkBank VPOS** üzerinde aktiftir. Diğer konnektörler için destek genişlemektedir — güncel matris için konsoldaki **Konnektörler** ekranına bakın.
</Note>

## Endpoint

```http theme={null}
POST /api/v1/payments/{transaction_id}/point-inquiry
```

Mevcut bir ödeme/3DS init kaydına bağlı kart için puan sorgular. Genellikle 3DS init sonrası, otorizasyon öncesi çağrılır — müşteriye "X puanınız var, kullanmak ister misiniz?" akışı için.

## İstek

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/payments/8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6/point-inquiry \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "extra_properties": {}
  }'
```

| Alan               | Tip    | Açıklama                                    |
| ------------------ | ------ | ------------------------------------------- |
| `extra_properties` | object | Konnektör-spesifik ek alanlar (genelde boş) |

## Yanıt

```json theme={null}
{
  "transaction_id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
  "status":         "three_d_secure_init_processing",
  "extra_properties": {
    "processed_at":      "2026-05-03T12:34:57.123+00:00",
    "point_balance":     "12500",
    "point_program":     "Bonus",
    "point_currency":    "TRY",
    "max_usable_points": "12500"
  }
}
```

<Note>
  Yanıttaki `status` alanı **mevcut Transaction durumunu yansıtır** (PointInquiry handler'ı durumu değiştirmez). Tipik akışta bu sorgu 3DS init sonrası yapılır, dolayısıyla `three_d_secure_init_processing` görürsünüz. Direkt sorgu (3DS olmadan) yapıldıysa `processing` veya `authorized` olabilir.
</Note>

| `extra_properties` alanı | Açıklama                                                  |
| ------------------------ | --------------------------------------------------------- |
| `point_balance`          | Mevcut puan bakiyesi (kuruş cinsinden TRY karşılığı)      |
| `point_program`          | Banka programı (Bonus, Maximum, Axess, World, Paraf, vb.) |
| `point_currency`         | Birim (genellikle TRY)                                    |
| `max_usable_points`      | Bu işlemde kullanılabilecek maksimum puan                 |

<Note>
  Konnektöre göre alan isimleri değişebilir — `point_balance` her konnektörde
  garanti değildir. Yanıt schema'sını **`extra_properties` altındaki gerçek
  anahtarlarla** çalışın; gelmeyen alanları boş varsayın.
</Note>

## Puan kullanarak ödeme

Şu an puan kullanımı **konnektöre özgü** bir akıştır — `CreatePaymentRequest.extra_properties` ile aktarılır:

```json theme={null}
{
  "amount":         { "amount": 15000, "currency": "TRY" },
  "installment":    1,
  "card":           { ... },
  "extra_properties": {
    "use_points":   "5000"
  }
}
```

Banka talebi onaylarsa kalan tutar (10.000 kuruş) karttan çekilir, 5.000 puan düşülür. Top-level standart bir `use_points` alanı yol haritasındadır.

## Hata response'ları

Hata yanıtı RFC 9457 problem+json formatındadır:

| HTTP  | `code`                        | Anlam                                                |
| ----- | ----------------------------- | ---------------------------------------------------- |
| `404` | `payment_not_found`           | İşlem bulunamadı                                     |
| `422` | `point_inquiry_not_supported` | Bu konnektör puan sorgusu desteklemiyor              |
| `422` | `point_inquiry_failed`        | Banka puan sorgusunu reddetti                        |
| `502` | `point_inquiry_exception`     | Sorgu sırasında konnektör tarafında beklenmeyen hata |

## Konnektör desteği matrisi

| Konnektör          | Point Inquiry          | Notlar                 |
| ------------------ | ---------------------- | ---------------------- |
| HalkBank VPOS      |                        | Paraf programı         |
| NestPay (genel)    | ⚠️ Konfigürasyon-bağlı | Banka anlaşmasına göre |
| Diğer konnektörler |                        | Yol haritasında        |