Efespay API ile ödeme alın.

1. 1. Test anahtarı alın

   Panelde Geliştirici → API anahtarları ekranından gizli test anahtarı oluşturun. Anahtar efp_test_sk_ ile başlar ve yalnız bir kez gösterilir; sunucunuzda ortam değişkeni olarak saklayın.

2. 2. Ödeme oturumu açın

   Tutarı kuruş olarak (amount_minor: 125000 = 1.250,00 TL) ve sipariş referansınızla gönderin. Yanıttaki url adresine müşteriyi yönlendirin.

   curl https://api.efespay.com/v1/payment-sessions \
     -H "Authorization: Bearer $EFESPAY_SECRET_KEY" \
     -H "Idempotency-Key: order-1001" \
     -H "Content-Type: application/json" \
     -d '{
       "order_reference": "ORDER-1001",
       "amount_minor": 125000,
       "currency": "TRY",
       "installment_options": [1, 3, 6],
       "return_url": "https://shop.example.com/order/1001"
     }'

3. 3. Sonucu doğrulayın

   Müşterinin sitenize dönmesi ödeme kanıtı değildir. Siparişi teslim etmeden önce GET /v1/payments/{id} ile ya da webhook ile doğrulanmış durumu okuyun.

   curl https://api.efespay.com/v1/payments/pay_… \
     -H "Authorization: Bearer $EFESPAY_SECRET_KEY"

curl https://api.efespay.com/v1 \
  -H "Authorization: Bearer $EFESPAY_SECRET_KEY"

• Anahtar yalnız sunucuda kullanılır; tarayıcıya ya da mobil uygulamaya konmaz.
• İstek başka bir işletme belirtemez: işletme ve mod (test | live) anahtardan gelir.
• Anahtar başına dakikada 600 istek; aşılırsa 429 rate_limited ve Retry-After başlığı.
• Her yanıt Efespay-Request-Id: req_… taşır; destek talebinde bu kimliği paylaşın.
• Hata mesajları Accept-Language başlığına göre Türkçe ya da İngilizce döner.

{
  "id": "ps_…",
  "object": "payment_session",
  "status": "open",
  "url": "https://efespay.com/pay/ps_…",
  "payment_id": "pay_…",
  "amount_minor": 125000,
  "installment_options": [
    { "installments": 1, "total_minor": 125000, "fee_minor": 0, "monthly_minor": 125000 },
    { "installments": 3, "total_minor": 129875, "fee_minor": 4875, "monthly_minor": 43292 }
  ],
  "expires_at": "2026-10-25T11:00:00.000Z"
}

• Yazma isteklerine Idempotency-Key ekleyin (≤ 255 karakter). Aynı anahtar ve aynı gövde 24 saat içinde kayıtlı yanıtı döndürür (Idempotent-Replayed: true).
• Aynı anahtarla farklı gövde 409 idempotency_conflict; ilk istek sürüyorsa 409 idempotency_in_progress.
• 5xx yanıtı saklanmaz; aynı anahtarla yeniden deneyebilirsiniz.
• Anahtar farklı olsa da aynı sipariş için ikinci açık oturum açılmaz (409 order_reference_in_use).

Ödeme durumları

Tarayıcı dönüşü (return_url) tek başına ödeme kanıtı değildir. Siparişi webhook ile ya da GET /v1/payments/{id} yanıtındaki doğrulanmış duruma göre güncelleyin.

POST https://shop.example.com/webhooks/efespay
Content-Type: application/json
User-Agent: Efespay-Webhooks/1.0
Efespay-Event-Id: evt_…
Efespay-Event-Type: payment.succeeded
Efespay-Signature: t=1792922400,v1=5f2c…

{
  "id": "evt_…",
  "object": "event",
  "type": "payment.succeeded",
  "created_at": "2026-10-25T10:00:00.000Z",
  "mode": "test",
  "data": {
    "object": {
      "id": "pay_…",
      "object": "payment",
      "status": "succeeded",
      "amount_minor": 125000,
      "order_reference": "ORDER-1001"
    }
  }
}

Efespay-Signature başlığındaki t ve v1 değerlerini okuyun. HMAC_SHA256(secret, t + "." + ham_gövde) değerini hex olarak hesaplayıp v1 ile sabit zamanlı karşılaştırın. t 5 dakikadan eskiyse isteği reddedin. Gövdeyi ayrıştırmadan önce ham hâliyle doğrulayın.

import crypto from "node:crypto";

export function verifyEfespaySignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post("/webhooks/efespay", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyEfespaySignature(req.body.toString("utf8"), req.get("Efespay-Signature"), process.env.EFESPAY_WEBHOOK_SECRET)) return res.sendStatus(400);
//   const event = JSON.parse(req.body); // deduplicate by event.id
//   res.sendStatus(200);
// });

• Uç noktanız 10 saniye içinde 2xx dönmelidir; yönlendirmeler (3xx) izlenmez.
• Başarısız teslimat 1 dk, 5 dk, 30 dk, 2 sa, 6 sa, 12 sa, 24 sa sonra yeniden denenir (toplam 8 deneme).
• 3 gün boyunca hiç başarılı teslim olmazsa uç noktası kapanır; işletme sahibine e-posta gider.
• Aynı olay birden çok kez gelebilir: Efespay-Event-Id ile tekilleştirin, eski bir olayla durumu geri almayın.
• İmza sırrı (whsec_…) yalnız uç noktası oluşturulurken ve yenilenirken bir kez gösterilir.

{
  "error": {
    "code": "order_reference_in_use",
    "message": "Bu sipariş referansıyla açık bir ödeme var.",
    "request_id": "req_…",
    "param": "order_reference"
  }
}

Ödeme sonucu hata kodları

Başarısız ödemede failure.code aşağıdaki kodlardan biridir; sağlayıcının ham kodu müşteriye gösterilmez, panelde işlem detayında yer alır. Teknik kodlar sağlayıcı kaynaklıdır ve kart reddinden ayrı sayılır.

• Test kartları yalnız test modunda ve Efespay test sağlayıcısıyla çalışır.
• Test sağlayıcısının sayfasında kart numarası girilmez; seçtiğiniz senaryo sunucuya gider.
• Zaman aşımı senaryoları belirsiz sonucu ve uzlaştırmayı denemeniz içindir.
• Test olayları da webhook olarak gelir; canlıya geçmeden doğrulama kodunuzu deneyin.