Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

Ağ kesintisi, timeout veya istemci tarafı hata durumlarında bir isteği iki kez göndermiş olabilirsiniz. Idempotency, aynı işlemin iki kez gerçekleştirilmemesini garanti eder.

​
Nasıl çalışır?

Yazma işlemi yapan tüm endpoint’ler (POST, PUT, PATCH, DELETE) bir Idempotency-Key header’ı kabul eder. Aynı anahtarla gönderilen ikinci istek, ilk yanıtın birebir aynısını döner — yeni bir işlem başlatmaz. 
POST /api/v1/payments
Idempotency-Key: 8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6

​
Anahtar gereksinimleri

KuralDeğer
FormatUUID v4 önerilir, herhangi bir string kabul edilir
Maksimum uzunluk128 karakter
Saklama süresi24 saat
Eşsiz olma kapsamıAynı API anahtarı + endpoint kombinasyonu içinde

​
Örnek senaryolar

  1. İstemci POST /payments isteği gönderir, Idempotency-Key: ABC123.
  2. Payven işlemi başarıyla gerçekleştirir, 200 OK döner.
  3. İstemci timeout aldığını sanıp aynı isteği aynı anahtarla tekrar gönderir.
  4. Payven, yeni bir ödeme oluşturmaz; ilk yanıtın aynısını döner.
  1. İki istek aynı anda atılır, ikisinde de Idempotency-Key: ABC123.
  2. Birinci istek işlenmeye başlar.
  3. İkinci istek, ilkinin tamamlanmasını bekler ve aynı yanıtı alır.
  1. İstemci Idempotency-Key: ABC123 ile 15000 kuruş ödeme atar.
  2. Aynı anahtarla 25000 kuruş ödeme atar.
  3. Payven 409 Conflict döner — anahtar zaten farklı bir payload için kullanılmış.
{
  "isSuccess": false,
  "code": "IDEMPOTENCY_PAYLOAD_MISMATCH",
  "message": "Bu idempotency anahtarı farklı bir istek için kullanılmış."
}
  1. 24 saat önce ABC123 anahtarıyla bir ödeme yapılmış.
  2. Aynı anahtar tekrar kullanılırsa yeni bir işlem oluşturulur (eski kayıt silinmiş).

​
Önerilen kullanım

var idempotencyKey = Guid.NewGuid().ToString();

// Retry policy ile birlikte
for (int attempt = 0; attempt < 3; attempt++)
{
    try
    {
        var request = new HttpRequestMessage(HttpMethod.Post, "/api/v1/payments");
        request.Headers.Add("Idempotency-Key", idempotencyKey);
        request.Content = JsonContent.Create(payload);
        var response = await http.SendAsync(request);
        return await response.Content.ReadFromJsonAsync<ApiResponse>();
    }
    catch (HttpRequestException) when (attempt < 2)
    {
        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
    }
}
Önerilen kural: Üst seviye iş kimliğinizi (örn. orderId) idempotency anahtarı olarak kullanın. Böylece aynı sipariş için yapılan tüm tekrar denemeler aynı işleme yönlendirilir.
Idempotency-Key: order-2026-001-payment

​
Hangi endpoint’lerde zorunlu?

Endpoint kategorisiIdempotency kullanımı
Ödeme oluşturma (POST /payments)Önerilir
3D init (POST /payments/3d/init)Önerilir
İade (POST /payments/{id}/refund)Zorunlu
İptal (POST /payments/{id}/void)Zorunlu
Capture (POST /payments/{id}/capture)Zorunlu
Webhook abonelik oluşturmaOpsiyonel
Liste/sorgu (GET) endpoint’leriİhtiyaç yok