Başlangıç
https://tahsilate-api.app-server.tahsilate.com.tr/external/vpos/v1
https://vpos-test.tahsilate.com.tr/external/vpos/v1
Dokümandaki tüm endpoint'ler bu adresin devamıdır; örneğin ödeme isteği https://tahsilate-api.app-server.tahsilate.com.tr/external/vpos/v1/payments adresine gönderilir. Gövdeli istekleri Content-Type: application/json ile gönderin. Test ortamında gerçek kart çekimi yapılmaz; test kartları ve senaryolar Test Ortamı sayfasındadır.
Endpoint'ler
| Method | Endpoint | Açıklama |
|---|---|---|
| POST | /external/vpos/v1/checkout-sessions | Ortak ödeme sayfası için oturum açar. |
| GET | /external/vpos/v1/checkout-sessions/{token} | Ödeme sayfası oturumunun durumunu döner. |
| POST | /external/vpos/v1/payments | Kart bilgisiyle 3D ödeme başlatır. |
| GET | /external/vpos/v1/payments/{transactionId} | Ödemenin durumunu döner. |
| POST | /external/vpos/v1/payments/{transactionId}/refund | Başarılı ödemeyi iade eder. |
| GET | /external/vpos/v1/installments?binCode=&amount= | Kart BIN'ine göre taksitleri listeler. |
| GET | /external/vpos/v1/commissions?amount= | Tutara göre tüm banka komisyonlarını hesaplar. |
Kimlik Doğrulama
Her üye işyerine bir apiKey ve bir secretKey verilir. Canlı ortam anahtarları TahsilatE panelinde (https://panel.tahsilate.com.tr) yer alır. Test ortamı anahtarları, test kullanıcı başvurunuz onaylandıktan sonra Profil sayfanızda görünür.
- apiKey her istekte
X-Api-Keybaşlığında gönderilir. - secretKey hiçbir istekte gönderilmez. İstekleri imzalamak ve bizden gelen imzaları (ödeme sonrası yönlendirme ve webhook) doğrulamak için kullanılır.
İsteği İmzalama
Her istekte üç başlık gönderilir:
X-Api-Key: API anahtarınız.X-Timestamp: İsteğin oluşturulduğu an, Unix zamanı (saniye). Sunucu saatimizden 5 dakikadan fazla farklıysa istek reddedilir.X-Signature: Aşağıdaki metnin secretKey ile HMAC-SHA256 imzası, küçük harf hex.
- METHOD: Büyük harfle,
GETveyaPOST. - YOL: Adresin alan adından sonraki kısmı, query string dahil ve gönderdiğiniz haliyle. Örnek:
/external/vpos/v1/installments?binCode=454360&amount=100.00 - GÖVDE: Gönderdiğiniz JSON'un kendisi. GET isteklerinde ve gövdesiz POST'larda boş metin. JSON'u bir kez string'e çevirip aynı string'i hem imzalayın hem gönderin; tekrar serileştirmek boşluk veya alan sırası farkıyla imzayı bozar.
İmzalı İstek Gönderme
Tüm endpoint'ler bu fonksiyonla çağrılabilir
TypeScriptStandart Cevap Yapısı
Tüm endpoint'ler aynı yapıda cevap döner. Sonucu HTTP durum koduna göre değerlendirin. Doğrulama hatalarında content hatalı alanların listesidir, diğer hatalarda null'dır.
Cevap Yapısı
HTTP Durum Kodları
| HTTP | Anlamı |
|---|---|
| 200 | İşlem başarılı. |
| 400 | İstek hatalı: eksik veya geçersiz alan, iş kuralı ihlali (örn. taksit bu tutar için kapalı). |
| 401 | Kimlik doğrulanamadı: başlık eksik, API anahtarı bulunamadı veya pasif, imza geçersiz, zaman damgası eski ya da imza tekrar kullanılmış. |
| 403 | API anahtarı bu işleme yetkili değil veya istek izin verilmeyen bir IP'den geldi. |
| 404 | Kayıt bulunamadı (örn. ödeme veya oturum). |
| 409 | Çakışma: transactionId daha önce kullanılmış veya ödeme iade edilebilir durumda değil. |
| 422 | Banka ödemeyi veya iadeyi reddetti; mesaj bankanın cevabıdır. |
| 429 | İstek sınırı aşıldı. |
IP Kısıtlaması
Panelde API anahtarınız için izin verilen sunucu IP adreslerini tanımlayabilirsiniz. Liste boşsa her IP'den istek kabul edilir. Liste doluysa yalnızca listedeki IP'lerden gelen istekler kabul edilir, diğerleri HTTP 403 ve "IP adresi geçersiz" hatası alır. Paylaşımlı barındırma gibi sunucu IP'sinin değişebildiği ortamlarda listeyi boş bırakın.
Rate Limiting
İstek sınırı her üye işyerine özel olarak ayarlanır ve her API anahtarı için ayrı sayılır.
Varsayılan:60 saniyede 10istek.
Sınır aşıldığında HTTP 429 ve "Rate limit aşıldı, lütfen daha sonra tekrar deneyiniz" mesajı döner.
Daha yüksek limitler için TahsilatE ile iletişime geçebilirsiniz.
