TahsilatE Logo
Geliştirici Ortamı

Başlangıç

Canlı ortam Base URL:
https://tahsilate-api.app-server.tahsilate.com.tr/external/vpos/v1
Test ortamı Base URL:
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

MethodEndpointAçıklama
POST/external/vpos/v1/checkout-sessionsOrtak ödeme sayfası için oturum açar.
GET/external/vpos/v1/checkout-sessions/{token}Ödeme sayfası oturumunun durumunu döner.
POST/external/vpos/v1/paymentsKart bilgisiyle 3D ödeme başlatır.
GET/external/vpos/v1/payments/{transactionId}Ödemenin durumunu döner.
POST/external/vpos/v1/payments/{transactionId}/refundBaş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-Key baş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.
secretKey'i tarayıcıda, mobil uygulamada veya herkese açık bir kod deposunda tutmayın. Tüm API çağrılarını kendi sunucunuzdan yapın.

İ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.
X-Timestamp + "\n" + METHOD + "\n" + YOL + "\n" + GÖVDE
  • METHOD: Büyük harfle, GET veya POST.
  • 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

TypeScript logoTypeScript
GET dışındaki isteklerde aynı imza ikinci kez kabul edilmez. Zaman aşımı veya ağ hatası sonrası isteği tekrarlarken yeni bir X-Timestamp ile yeniden imzalayın.

Standart 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ı

1234

HTTP Durum Kodları

HTTPAnlamı
200İşlem başarılı.
400İstek hatalı: eksik veya geçersiz alan, iş kuralı ihlali (örn. taksit bu tutar için kapalı).
401Kimlik doğrulanamadı: başlık eksik, API anahtarı bulunamadı veya pasif, imza geçersiz, zaman damgası eski ya da imza tekrar kullanılmış.
403API anahtarı bu işleme yetkili değil veya istek izin verilmeyen bir IP'den geldi.
404Kayıt bulunamadı (örn. ödeme veya oturum).
409Çakışma: transactionId daha önce kullanılmış veya ödeme iade edilebilir durumda değil.
422Banka ö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.