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.
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.
Endpoint
POST /api/v1/payments/{transaction_id}/point-inquiry
İstek
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
{
"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"
}
}
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.
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 |
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.
Puan kullanarak ödeme
Şu an puan kullanımı konnektöre özgü bir akıştır — CreatePaymentRequest.extra_properties ile aktarılır:
{
"amount": { "amount": 15000, "currency": "TRY" },
"installment": 1,
"card": { ... },
"extra_properties": {
"use_points": "5000"
}
}
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 |
