API Referansı

OdemeNet API endpoint'leri, parametreleri ve yanıt formatları

Kategoriler

Kimlik Doğrulama

Not: Tüm API istekleri için Authorization header'ında Bearer token gönderilmelidir.

POST /api/auth/login

Açıklama: API'ye erişim için JWT token alınır.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
apiKey	string	Zorunlu	Firma API anahtarı
apiSecret	string	Zorunlu	Firma API gizli anahtarı

Örnek İstek

{
  "apiKey": "YOUR_API_KEY",
  "apiSecret": "YOUR_API_SECRET"
}

Başarılı Yanıt (200 OK)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Ödeme İşlemleri

POST /api/payment/3dsecure

Açıklama: 3D Secure ile güvenli ödeme işlemi başlatır.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
amount	decimal	Zorunlu	Ödeme tutarı
cardNumber	string	Zorunlu	Kart numarası (16 haneli)
cardHolderName	string	Zorunlu	Kart üzerindeki isim
expireMonth	string	Zorunlu	Son kullanma ayı (MM)
expireYear	string	Zorunlu	Son kullanma yılı (YYYY)
cvv	string	Zorunlu	CVV güvenlik kodu
installment	int	Opsiyonel	Taksit sayısı (1-12)
orderId	string	Zorunlu	Sipariş numarası

Kart Yönetimi

POST /api/card/save

Açıklama: Kart bilgilerini güvenli şekilde saklar.

Güvenlik: Kart bilgileri PCI DSS uyumlu şekilde şifrelenerek saklanır.

GET /api/card/list/{customerId}

Açıklama: Müşteriye ait kayıtlı kartları listeler.

DELETE /api/card/delete/{cardId}

Açıklama: Kayıtlı kartı sistemden siler.

Taksit İşlemleri

GET /api/installment/options

Açıklama: BIN numarasına göre mevcut taksit seçeneklerini getirir.

Query Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
binNumber	string	Zorunlu	Kart BIN numarası (ilk 6 hane)
amount	decimal	Zorunlu	İşlem tutarı

İşlem Sorgulama

GET /api/transaction/{transactionId}

Açıklama: İşlem durumunu sorgular.

POST /api/transaction/refund

Açıklama: İşlem iadesi yapar.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
transactionId	string	Zorunlu	İşlem ID
amount	decimal	Opsiyonel	İade tutarı (boş ise tam iade)

Webhook Yönetimi

Webhook Sistemi: OdemeNet, önemli olaylar gerçekleştiğinde belirlediğiniz URL'lere güvenli POST istekleri gönderir. Webhook'lar HMAC-SHA256 ile imzalanır ve yeniden deneme mekanizması vardır.

GET /api/webhook

Açıklama: Firmaya ait tüm webhook'ları listeler.

Query Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
isActive	bool	Opsiyonel	Aktif webhook'ları filtrele

Başarılı Yanıt (200 OK)

[
  {
    "id": "uuid",
    "url": "https://your-site.com/webhook",
    "description": "Ödeme bildirimleri",
    "events": ["payment.succeeded", "payment.failed"],
    "isActive": true,
    "retryCount": 3,
    "timeoutSeconds": 30,
    "createdAt": "2025-01-21T08:30:00Z",
    "lastTriggeredAt": "2025-01-21T10:15:00Z",
    "successCount": 45,
    "failureCount": 2
  }
]

GET /api/webhook/{id}

Açıklama: Belirli bir webhook'un detay bilgilerini getirir.

Path Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
id	guid	Zorunlu	Webhook ID'si

POST /api/webhook

Açıklama: Yeni webhook oluşturur ve güvenlik anahtarı üretir.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
url	string	Zorunlu	Webhook URL'i (HTTPS zorunlu)
description	string	Opsiyonel	Webhook açıklaması
events	array	Zorunlu	Dinlenecek event tipleri
retryCount	int	Opsiyonel	Yeniden deneme sayısı (varsayılan: 3)
timeoutSeconds	int	Opsiyonel	Timeout süresi (varsayılan: 30)

Örnek İstek

{
  "url": "https://your-site.com/webhook",
  "description": "Ödeme bildirimleri",
  "events": ["payment.succeeded", "payment.failed"],
  "retryCount": 3,
  "timeoutSeconds": 30
}

Başarılı Yanıt (200 OK)

{
  "message": "Webhook başarıyla oluşturuldu",
  "id": "webhook-uuid",
  "secret": "generated-secret-key",
  "warning": "Bu secret'ı güvenli bir yerde saklayın."
}

PUT /api/webhook/{id}

Açıklama: Mevcut webhook'u günceller.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
url	string	Zorunlu	Webhook URL'i
description	string	Opsiyonel	Webhook açıklaması
events	array	Zorunlu	Dinlenecek event tipleri
isActive	bool	Zorunlu	Webhook aktif durumu
retryCount	int	Zorunlu	Yeniden deneme sayısı
timeoutSeconds	int	Zorunlu	Timeout süresi

DELETE /api/webhook/{id}

Açıklama: Webhook'u sistemden kalıcı olarak siler.

Uyarı: Bu işlem geri alınamaz. Webhook silindiğinde tüm geçmiş loglar da silinir.

POST /api/webhook/{id}/regenerate-secret

Açıklama: Webhook'un güvenlik anahtarını yeniler.

Başarılı Yanıt (200 OK)

{
  "message": "Secret başarıyla yenilendi",
  "secret": "new-generated-secret-key",
  "warning": "Eski secret artık geçersizdir."
}

POST /api/webhook/{id}/test

Açıklama: Webhook'u test eder ve örnek payload gönderir.

İstek Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
eventType	string	Zorunlu	Test edilecek event tipi
samplePayload	object	Opsiyonel	Özel test verisi

GET /api/webhook/{id}/logs

Açıklama: Webhook'un gönderim loglarını listeler.

Query Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
eventType	string	Opsiyonel	Event tipine göre filtrele
isSuccess	bool	Opsiyonel	Başarı durumuna göre filtrele
startDate	datetime	Opsiyonel	Başlangıç tarihi
endDate	datetime	Opsiyonel	Bitiş tarihi
page	int	Opsiyonel	Sayfa numarası (varsayılan: 1)
pageSize	int	Opsiyonel	Sayfa boyutu (varsayılan: 50)

Başarılı Yanıt (200 OK)

{
  "data": [
    {
      "id": "log-uuid",
      "webhookId": "webhook-uuid",
      "webhookUrl": "https://your-site.com/webhook",
      "eventType": "payment.succeeded",
      "requestPayload": "{\"eventType\":\"payment.succeeded\"...}",
      "responseStatus": "200 OK",
      "responseCode": 200,
      "responseBody": "{\"status\":\"received\"}",
      "responseTimeMs": 150,
      "attemptNumber": 1,
      "isSuccess": true,
      "errorMessage": null,
      "triggeredAt": "2025-01-21T10:15:00Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 123,
  "totalPages": 3
}

POST /api/webhook/logs/{logId}/retry

Açıklama: Başarısız webhook'u yeniden gönderir.

Path Parametreleri

Parametre	Tip	Zorunluluk	Açıklama
logId	guid	Zorunlu	Webhook log ID'si

GET /api/webhook/events

Açıklama: Sistemde desteklenen tüm event tiplerini listeler.

Başarılı Yanıt (200 OK)

[
  {
    "type": "payment.succeeded",
    "description": "Ödeme başarıyla tamamlandığında",
    "samplePayload": {
      "eventType": "payment.succeeded",
      "transactionId": "TRX123456",
      "amount": 100.00,
      "currency": "TRY",
      "timestamp": "2025-01-21T10:15:00Z"
    }
  },
  {
    "type": "payment.failed",
    "description": "Ödeme başarısız olduğunda",
    "samplePayload": {
      "eventType": "payment.failed",
      "transactionId": "TRX123456",
      "errorCode": "ERR001",
      "errorMessage": "Yetersiz bakiye",
      "timestamp": "2025-01-21T10:15:00Z"
    }
  },
  {
    "type": "refund.completed",
    "description": "İade işlemi tamamlandığında",
    "samplePayload": {
      "eventType": "refund.completed",
      "refundId": "REF123456",
      "originalTransactionId": "TRX123456",
      "amount": 100.00,
      "timestamp": "2025-01-21T10:15:00Z"
    }
  }
]

GET /api/webhook/signature-example

Açıklama: Webhook imza doğrulama örneği ve rehberi.

İmza Doğrulama

Güvenlik: Tüm webhook istekleri X-Webhook-Signature header'ında HMAC-SHA256 imzası ile gönderilir.

JavaScript Örnek Kod

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expectedSignature = crypto
        .createHmac('sha256', secret)
        .update(JSON.stringify(payload))
        .digest('hex');
    
    return signature === expectedSignature;
}

// Kullanım
const isValid = verifyWebhookSignature(
    req.body,
    req.headers['x-webhook-signature'],
    'your-webhook-secret'
);

C# Örnek Kod

using System.Security.Cryptography;
using System.Text;

public bool VerifyWebhookSignature(string payload, string signature, string secret)
{
    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
    {
        var expectedSignature = Convert.ToHexString(
            hmac.ComputeHash(Encoding.UTF8.GetBytes(payload))
        ).ToLower();
        
        return signature == expectedSignature;
    }
}

Önemli Notlar:

Webhook URL'lerinin HTTPS protokolü kullanması zorunludur
Webhook istekleri 30 saniye timeout süresine tabidir
Başarısız istekler otomatik olarak 3 kez yeniden denenir
200-299 arası HTTP status kodları başarılı sayılır
İmza doğrulamasını mutlaka uygulayın