3D Ödeme
3D Ödeme Servisi İstek Modeli
| Method | Endpoint | Body |
|---|---|---|
| POST | /payments | JSON |
3D Ödeme Servisi İşlem Akışı
- Üye işyeri kullanıcı, kart, sepet, ödeme tutar ve taksit bilgilerini, ödemenin sonucunun bildirilmesini istediği kendi web adresi (backUrl) ile birlikte TahsilatE 3D ödeme servisine istek gönderir ve işlemi başlatır.
- TahsilatE, bilgileri değerlendirerek üye iş yerine cevap mesajını gönderir.
- Üye işyeri, aldığı cevabı değerlendirir ve ödeme kabul edildi ise cevaptaki form yada url bilgisini type paramtetresine uygun şekilde kullanarak kullanıcının 3d doğrulama ekranına yönlendirilmesini sağlar.
- TahsilatE, 3D doğrulama işlemlerini sonuçlandırır ve sonucu üye işyerinin backUrl adresine POST eder.
3D Ödeme Servisi İstek Mesajı Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| terminal | object | Evet | Üye işyerine ait terminal bilgileri. |
| transaction | object | Evet | İşlem bilgileri. |
| creditCard | object | Evet | Kart bilgileri. |
| customer | object | Evet | Müşteri bilgileri. |
| items | array | Evet | Ürün/Hizmet/Sepet bilgileri. |
Terminal Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| apiKey | string | Evet | Üye işyerine ait apiKey bilgisi. |
Transaction Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| amount | number | Evet | Ödeme tutarı. |
| installment | number | Evet | Taksit sayısı. |
| transactionId | string | Evet | İşlem ID'si. |
| backUrl | string | Evet | İşlem sonucunun bildirilmesini istediği kendi web adresi. |
| invoiceDescription | string | Evet | Fatura açıklaması. |
| hash | string | Evet | İşleme özel hash. |
| testMode | boolean | Evet | Test modu. |
Credit Card Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| cardNumber | string | Evet | Kart numarası. |
| cardHolderName | string | Evet | Kart sahibi adı. |
| expiryMonth | string | Evet | Kart son kullanma ayı. |
| expiryYear | string | Evet | Kart son kullanma yılı. |
| cvv | string | Evet | Kart güvenlik kodu. |
Customer Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| name | string | Evet | Müşteri adı. |
| surname | string | Evet | Müşteri soyadı. |
string | Evet | Müşteri e-posta adresi. | |
| phoneNumber | string | Evet | Müşteri telefon numarası. |
| clientIp | string | Evet | Müşteri IP adresi. |
| city | string | Evet | Müşteri şehir. |
| district | string | Evet | Müşteri ilçe. |
| address | string | Evet | Müşteri adresi. |
Items Parametreleri
| Parametre | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| productId | string | Evet | Ürüne üye işyeri tarafından verilen ID. |
| productName | string | Evet | Ürün adı. |
| productCategory | string | Evet | Ürün kategorisi. |
| productDescription | string | Evet | Ürün açıklaması. |
| productPrice | number | Evet | Ürün fiyatı. |
| quantity | number | Evet | Ürün adeti. |
Örnek İstek JSON
Ödeme işlemi için örnek request body
Hash Oluşturma (Request Hash)
3D ödeme entegrasyonunda güvenli bir şekilde hash oluşturmak kritik bir öneme sahiptir. Hash, ödeme isteğinin bütünlüğünü ve güvenliğini sağlayan bir mekanizmadır.
Hash Oluşturma Algoritması
Hash oluşturmak için aşağıdaki bilgiler sırayla birleştirilir:
- transactionId: İşlem benzersiz tanımlayıcısı
- amount: Ödeme tutarı
- installment: Taksit sayısı
- apiKey: API anahtarı
Bu bilgiler | (dikey çizgi) ile ayrılarak tek bir string oluşturulur ve secretKey kullanılarak HMAC-SHA256 ile hash'lenir.
Hash Oluşturma Örneği
transactionId: 'txn_123456'
amount: 100.50
installment: 3
apiKey: 'api_key_123'
secretKey: 'secret_key_456'
Birleştirilmiş string: txn_123456|100.50|3|api_key_123
Hash Oluşturma Kodu
Çoklu dilde güvenli hash oluşturma örneği
TypeScriptGüvenlik Uyarıları
- Secret Key'i asla client-side kodlarda veya açık bir şekilde paylaşmayın.
- Her ödeme isteği için unique bir transactionId kullanın.
- Hash hesaplamasını her zaman server-side yapın.
3D Ödeme Servisi Cevap Mesajı Parametreleri
Bu response yapısı aynı zamanda tüm işlemlerde standart response yapısıdır.
| Parameter | Type | Description |
|---|---|---|
| message | string | İşlem sonucu mesajı. |
| content | object | array | null | İşlem sonucu içeriği. (Validasyon hatası durumunda array, diğer hatalarda null döner) |
3D Ödeme Servisi Başarılı Cevap İçeriği (content alanı)
| Parameter | Type | Description |
|---|---|---|
| transactionId | string | İşlem ID'si. |
| amount | number | Ödeme tutarı. |
| form | string | Bankanın 3d doğrulama ekranına yönlendirmek için kullanılacak form. |
| url | string | Bankanın 3d doğrulama ekranına yönlendirmek için kullanılacak URL. |
| type | string | Sonuç veri tipi, form olması durumunda form'u ekrana basmanız, url olması durumunda url'e redirect yapmanız gerekmektedir. |
Örnek Başarılı Cevap JSON
Ödeme işlemi için örnek başarılı response body
3D Ödeme Servisi Validasyon Hatası Cevap İçeriği (content alanı)
| Parameter | Type | Description |
|---|---|---|
| field | string | Hatanın hangi field'da olduğunu gösterir. (objelerde nokta notasyonu ile gelir örn: transaction.amount) |
| message | string | Hata mesajı. İlgili field'da neyin yanlış olduğunu gösterir. |
Validasyon Hatası Örnek JSON
Ödeme işlemi için örnek validasyon hatası response body
3D Ödeme Servisi Hata Yanıtı
| Parameter | Type | Description |
|---|---|---|
| message | string | Hata mesajı. Örneğin apiKey parametresi gönderilmediğinde "API key bulunamadı" hatası alırsınız. |
| content | null | Validasyon hatası dışındaki hata durumlarında null döner. |
Hata Yanıtı Örnek JSON
Ödeme işlemi için örnek hata response body
3D Ödeme Sonrası Yönlendirme
TahsilatE, 3D doğrulama işlemini sonuçlandırır ve sonucu üye işyerinin backUrl adresine redirect eder. (GET) Sonuç parametreleri ile ödeme tamamlanır veya hata döner.
TahsilatE'den Gelen Callback
Bu değerler query string olarak backUrl adresine gönderilir.
Ödeme Sonuç Kontrolü ile Doğrulama
Son adımda hash doğrulandıktan sonra işlemin gerçekten başarılı olduğuna emin olmak ve işlemi tamamlamak için Ödeme Sonuç Kontrol özelliğini kullanmanız önerilir.
GET /payments/<transactionId> endpoint'ine sorgu yapıp, dönen sonucu dikkate alırsanız en sağlıklı entegrasyonu sağlamış olursunuz.
GET /payments/123456789// Dönen response'a göre işlemi tamamlayın