Kanıt Servisiniz

Bir müşteri bankası aracılığıyla bir ödemeye itiraz ettiğinde banka tek bir soru sorar: Bu kart sahibi, şartlarınızı görmüş olarak ürünü satın aldı mı, teslim aldı mı ve kullandı mı? Ödeme sağlayıcınız ödemenin kendisini bilir. Gerisini siz bilirsiniz: satın almanın nereden yapıldığını, müşterinin sonrasında oturum açıp açmadığını, ödeme sırasında neyi kabul ettiğini, birbirinize neler yazdığınızı.

Kanıt servisi, Chargeless'ın bir itirazı yanıtlarken başvurduğu, size ait tek bir HTTPS uç noktasıdır. Her ödeme sağlayıcısıyla çalışır: Stripe kullanan bir çalışma alanı da, faturalamayı kendi sisteminde yürüten bir çalışma alanı da servisi aynı şekilde bağlar.

Bu sayfa, sözleşmeyi örneklerle anlatır. Şemalar, sözleşme dosyalarında schemas/merchant-evidence/v1/ altındadır (request.json, response.json); bu sayfayla şemalar arasında fark varsa şemalar esas alınır. Şemaları, örnekleri ve imza test vektörüyle birlikte merchant-evidence-v1-contract.zip olarak indirebilirsiniz.

Yanıtınız Nasıl Kullanılır

• Chargeless kanıtı dört kaynaktan oluşturur: ödemeye ilişkin kendi kaydı, kendisi üzerinden geçenler (talepler, yanıtlar), ödeme sağlayıcınızın ödeme hakkında bildirdikleri ve sizin yanıtınız. Kanıttaki her alanın kaynağı belirtilir.
• Ham değerler kendi alanlarına yerleştirilir: satın almanın IP adresi "customer purchase IP" alanına, kullanım olaylarınız "access activity log" alanına, belgeleriniz ilgili dosya alanlarına.
• Argümanı (serbest metin bölümünü) bir asistan, "16 kullanım olayının 14'ü satın almanın yapıldığı IP adresinden geldi" gibi cümlelerden oluşan bir özetten yazar. Asistan hiçbir zaman IP adresi, cihaz kimliği, ad, e-posta ya da adres görmez; kayıtlarınızın desteklemediği bir cümle çıkarılır.
• Yanıtınız saklanmaz. Chargeless hangi bölümlerin bulunduğunu ve her alanın nereden geldiğini kaydeder, değerleri asla saklamaz. Gönderilenler ödeme sağlayıcınızda durur; panel bunları sağlayıcıdan okuyarak gösterir.
• Yanıtınız sizin beyanınızdır. Kart ağına sizin adınıza iletilir. Kayıtlarınız neyi gösteriyorsa onu yanıtlayın.

Hiçbir şey saklanmadığı için tek bir itiraz için servisinize birden fazla kez sorulur: itiraz açıldığında (vakasında nelerin bulunduğunu ve nelerin eksik olduğunu göstermek için) ve kanıt gönderilirken bir kez daha. Bu bir okuma isteğidir; her seferinde aynı şekilde yanıt verin.

Kayıtlarınızı saklayın. Bir itiraz ödemeden 120 gün sonra, bazı durumlarda 540 güne kadar sonra gelebilir. O zamana kadar günlüklerini silmiş (log rotation) bir servisin sunabileceği bir şey kalmaz.

Bağlantıyı Kurma

Ayarlar → Kanıt Servisi (Bağlantılar altında). URL'yi girin, kaydedin ve imza anahtarını kopyalayın: anahtar yalnızca bir kez gösterilir (srme_…). Test İsteği Gönder, "test": true ve yapay kimliklerle imzalı tek bir çağrı yapar; boş yanıt da dahil geçerli her yanıt testi geçer. URL'yi ya da anahtarı değiştirmek için doğrulama uygulamanızdaki kod gerekir.

URL, 443 numaralı portta https kullanmalı ve Chargeless'ın internet üzerinden erişebileceği bir adreste olmalıdır. Erişilebilir olması herkese açık olduğu anlamına gelmez: her istek imzalanır ve servis kendi API'nizin kimlik bilgilerinin arkasında kalabilir (aşağıda). Yönlendirmeler izlenmez.

URL, sorgu dizesi (query string) içermeyen tek ve sabit bir adrestir (? işaretinden sonra hiçbir şey yoktur). Hangi tahsilatın ve hangi müşterinin sorulduğu isteğin gövdesinde gelir: ödeme sağlayıcınızın tahsilata, ödemeye, müşteriye ve aboneliğe verdiği kimlikler (Stripe'ta ch_…, pi_…, cus_…, sub_…) ve bunlara sağlayıcıda eklediğiniz metadata. Servisiniz kendi kayıtlarını bu bilgilerle bulur (aşağıdaki "Kayıtlarınızı bulma" bölümüne bakın).

Servisi Kendi API'nizin Arkasında Tutma

Servis API ağ geçidinizin (API gateway) arkasındaysa, ağ geçidinin istediği bilgileri aynı sayfadaki API'nizin Kimlik Bilgileri alanından Chargeless'a verin:

• Erişim token'ı: Authorization: Bearer <token> olarak gönderilir. 1 ile 4.096 arasında görünür ASCII karakter.
• Kendi başlıklarınız: en fazla üç tane; bir API anahtarı ve gizli anahtarı için ya da ağ geçidiniz bunlara hangi adı veriyorsa, örneğin AccessKey ve AccessSecret ya da X-Api-Key. Başlık adı 1 ile 64 karakter arasında harf, rakam ve tireden oluşur; değeri en fazla 1.024 yazdırılabilir ASCII karakterdir. Authorization (erişim token'ı için kullanılır), Host, Cookie, Content-*, User-Agent, X-SupportRoute-* ve X-SR-* bize ya da taşıma katmanına aittir ve ayarlanamaz.

Bu bilgiler, test isteği de dahil her istekte imzayla birlikte gönderilir:

POST /v1/chargeless/evidence HTTP/1.1
Host: api.example.com
Authorization: Bearer 9f31c2…
AccessKey: ak_7721…
AccessSecret: as_5510…
X-SupportRoute-Timestamp: 1794400800
X-SupportRoute-Signature: v1=…
X-SR-Request-Id: 019a7c1e-5b0a-7c3e-9d21-4f6a8b0c2d4f

• Şifrelenerek saklanır, bir daha gösterilmez. Panel, bir erişim token'ının kayıtlı olup olmadığını ve hangi başlıkların kayıtlı olduğunu adlarıyla gösterir. Birini değiştirmek için yeniden girin; gönderilmesini durdurmak için kaldırın.
• URL'ye bağlıdır. Kayıtlı bir kimlik bilgisi yalnızca girildiği URL'ye gönderilir, başka hiçbir adrese gönderilmez. URL'yi değiştirdiğinizde kayıtlı her kimlik bilgisini yeniden girin ya da kaldırın; aksi halde değişiklik kaydedilmez.
• İmza yine gönderilir. Kimlik bilgilerini ağ geçidiniz, imzayı servisiniz kontrol edebilir; ikisini birlikte de kullanabilirsiniz. İmza ayrıca gövdenin değiştirilmediğini ve isteğin yeni olduğunu kanıtlar; sabit bir token bunu sağlamaz. Bu yüzden mümkün olan her yerde imzayı kontrol edin.
• Chargeless'a yalnızca bu servisin yanıtladığı verileri okuyabilen, kendisine özel bir kimlik bilgisi tanımlayın; böylece başka hiçbir şeyi etkilemeden onu iptal edebilirsiniz. Basic authentication (kullanıcı adı ve parola) desteklenmez.

İstek

POST /chargeless/evidence HTTP/1.1
Host: evidence.example.com
Accept: application/json
Content-Type: application/json
User-Agent: Chargeless (merchant-evidence/v1)
X-SupportRoute-Timestamp: 1794400800
X-SupportRoute-Signature: v1=a6f60ff81a282bf03b40eb77ff15daff81b27cef33f100d312bd16a96a4fb248
X-SR-Request-Id: 019a7c1e-5b0a-7c3e-9d21-4f6a8b0c2d4f

{"contract":"merchant-evidence/1.0","request_id":"019a7c1e-5b0a-7c3e-9d21-4f6a8b0c2d4f",…}

• İmza, başında v1= bulunan ve imza anahtarınızla şu metin üzerinden hesaplanan HMAC-SHA256 değerinin küçük harfli hex gösterimidir: {timestamp}\n{METHOD}\n{host}\n{path}\n\n{body}. Metnin parçaları sırasıyla: gönderildiği haliyle zaman damgası başlığı, POST, gönderildiği haliyle host (küçük harfle; port 443 ise port yazılmaz), gönderildiği haliyle yol (path), boş bir satır ve ham gövde baytları. Bu, işletmenin barındırdığı sağlayıcıların (merchant-provider) imzasının idempotency anahtarı içermeyen halidir; tek bir doğrulayıcı ikisinde de kullanılabilir. schemas/merchant-evidence/examples/v1/signature.json bir test vektörüdür: yukarıdaki istek, srme_test_7d1e4b9c2a6f ile imzalanmış haliyle.
• Eşleşmeyen bir imzayı ya da beş dakikadan fazla sapan bir zaman damgasını 401 ile reddedin. İmzaları sabit zamanlı (constant time) karşılaştırın.
• 10 saniye içinde yanıt verin. Daha geç gelen bir yanıt, başka bir durum kodu ya da sözleşmenin kabul etmediği bir gövde, yanıt verilmemiş sayılır: kanıt sizin bölümünüz olmadan oluşturulur ve itirazın vakasında nedeni belirtilir. Hata veren bir servis bir itirazı hiçbir zaman geciktirmez.

Gerçek bir istek (schemas/merchant-evidence/examples/v1/request.fraud.json):

{
  "contract": "merchant-evidence/1.0",
  "request_id": "019a7c1e-5b0a-7c3e-9d21-4f6a8b0c2d4e",
  "tenant_id": "01999999-0000-7000-8000-000000000001",
  "asked_at": "2026-11-11T12:00:00Z",
  "test": false,
  "dispute": {
    "ref": "du_1SabcDEF",
    "reason": "fraudulent",
    "category": "fraud",
    "amount": { "amount_minor": 4999, "currency": "USD" },
    "opened_at": "2026-11-09T08:00:00Z",
    "evidence_due_by": "2026-11-23T23:59:59Z"
  },
  "charge": {
    "provider": "stripe",
    "connection_id": "01999999-0000-7000-8000-0000000000c1",
    "ref": "ch_3SabcDEF",
    "payment_ref": "pi_3SabcDEF",
    "amount": { "amount_minor": 4999, "currency": "USD" },
    "created_at": "2026-10-01T10:00:00Z",
    "metadata": { "order_id": "ord_88213" },
    "card": { "brand": "visa", "last4": "4242" }
  },
  "customer": { "kind": "account", "ref": "cus_Rabc123", "metadata": { "user_id": "user_771" } },
  "subscription": { "ref": "sub_1Sabc", "metadata": { "plan": "pro", "workspace": "ws_4410" } },
  "prior_charges": [
    { "ref": "ch_3RoldA", "payment_ref": "pi_3RoldA", "amount": { "amount_minor": 4999, "currency": "USD" }, "created_at": "2026-05-01T10:00:00Z" },
    { "ref": "ch_3RoldB", "amount": { "amount_minor": 4999, "currency": "USD" }, "created_at": "2026-04-01T10:00:00Z" }
  ]
}

Kayıtlarınızı Bulma

Chargeless isteğe kendi tarafından hiçbir e-posta, ad ya da adres eklemez. Satın almayı ve müşteriyi iki yoldan bulabilirsiniz:

• Sisteminizin sakladığı sağlayıcı kimlikleriyle: tahsilat (charge.ref), ona ait ödeme (charge.payment_ref, Stripe'ta PaymentIntent), müşteri (customer.ref) ya da abonelik (subscription.ref). Misafir ödemelerinde customer.kind: "guest" bulunur, ref bulunmaz.
• Kendi kimliklerinizle, bunları sağlayıcıda saklıyorsanız: tahsilat, müşteri ve abonelik üzerindeki metadata, bu nesnelere sağlayıcıda sizin eklediğiniz bilgilerdir (Stripe: metadata) ve sağlayıcının şu anda tuttuğu haliyle size geri iletilir. Ödemeye eklenmiş bir sipariş numarası ya da müşteriye eklenmiş kullanıcı kimliğiniz yeterlidir.

metadata hakkında:

• Sizindir ve size geri döner. Chargeless bu istek için onu sağlayıcıdan okur, hiçbir kısmını saklamaz, hiçbir modele göstermez ve yorumlamaz. İçine bir e-posta adresi koyarsanız o adres istekte size geri gelir; başka kimse görmez.
• Nesne başına en fazla 50 çift; anahtar 1 ile 40 karakter, değer en fazla 500 karakter. Bu sınırların dışındaki ya da kart numarasına benzeyen bir çift isteğe eklenmez. Metadata'sı olmayan bir nesnede metadata alanı bulunmaz; metadata'sı okunamayan bir nesnede de bulunmaz.
• Stripe'ta bir PaymentIntent'e eklediğiniz değerler, tahsilat oluşturulduğu andaki haliyle tahsilatta da yer alır. Subscription ya da Customer nesnesine eklediğiniz değerler tahsilatta yer almaz: bunlar için subscription.metadata ve customer.metadata alanlarına bakın. Checkout Session'ın kendi metadata alanı bunların hiçbirinde yer almaz: oturumu oluştururken payment_intent_data.metadata ya da subscription_data.metadata ayarlayın veya kimliğinizi Customer nesnesinde saklayın.
• Bu alan şu anda Stripe ödemelerinde gelir; diğer sağlayıcılarda bulunmaz.

dispute.category müşterinin neyi iddia ettiğini, dolayısıyla yanıtınızın hangi bölümlerinin en çok önem taşıdığını gösterir.

Yanıt

En fazla 6 MiB'lık bir JSON gövdesiyle HTTP 200. Yalnızca request_id zorunludur: bildiklerinizi yanıtlayın, gerisini göndermeyin.

{
  "request_id": "019a7c1e-5b0a-7c3e-9d21-4f6a8b0c2d4e",
  "customer": {
    "account_id": "user_771",
    "account_created_at": "2026-01-13T09:30:00Z",
    "name": "Jane Roe",
    "email": "[email protected]",
    "email_verified_at": "2026-01-13T09:41:00Z"
  },
  "purchase": {
    "at": "2026-10-01T10:00:00Z",
    "ip": "203.0.113.7",
    "device_id": "dev_9f8e7d6c",
    "billing_address": { "line1": "1 Main Street", "city": "Springfield", "state": "IL", "postal_code": "62701", "country": "US" },
    "product": { "name": "Pro plan", "description": "Monthly access to the editor and its exports.", "kind": "subscription" }
  },
  "terms": [
    { "kind": "refund_policy", "accepted_at": "2026-10-01T10:00:00Z", "version": "2026-05", "how": "checkbox at checkout, linked to the full text", "url": "https://acme.example/refunds" }
  ],
  "usage": {
    "first_at": "2026-10-01T10:05:00Z",
    "last_at": "2026-11-10T18:20:00Z",
    "count": 41,
    "events": [
      { "at": "2026-10-01T10:05:00Z", "action": "login", "ip": "203.0.113.7", "device_id": "dev_9f8e7d6c" },
      { "at": "2026-10-03T14:00:00Z", "action": "export", "ip": "203.0.113.7", "device_id": "dev_9f8e7d6c", "detail": "project 12, 3 files" }
    ]
  },
  "delivery": { "kind": "digital", "delivered_at": "2026-10-01T10:00:30Z" },
  "cancellation": { "requested": false, "reminder_sent_at": "2026-09-28T09:00:00Z" },
  "communications": [
    { "at": "2026-10-04T09:00:00Z", "from": "customer", "channel": "email", "text": "Thanks, the export works now." }
  ],
  "prior_charges": [
    { "ref": "ch_3RoldA", "ip": "203.0.113.7", "account_id": "user_771" },
    { "ref": "ch_3RoldB", "device_id": "dev_9f8e7d6c", "account_id": "user_771" }
  ]
}

Kurallar:

• Asla kart numarası göndermeyin. Bir kimlikte, adda, e-postada ya da adreste kart numarasına benzeyen bir değer bulunursa yanıtın tamamı geçersiz sayılır. Bir mesajın, bir kaydın ya da bir kişinin yazdığı başka bir metnin içinde ya da bir takip numarasında bulunursa, yanıtı başka hiçbir şey okumadan önce silinir.
• Zamanlar, saat farkı (offset) içeren RFC 3339 biçimindedir (2026-10-01T10:00:00Z). Ülkeler iki harfli kodla yazılır.
• accepted_at içermeyen şartlar kabul edilmiş sayılmaz.
• cancellation altındaki "requested": false bir beyandır: müşterinin iptal istediğine dair hiçbir kaydınız olmadığını bildirir. Bunu yalnızca gerçekten böyleyse gönderin.
• Ödeme sağlayıcıları her dosya alanı için tek dosya kabul eder: aynı alana ait ikinci dosya uncategorized olarak eklenir, üçüncüsü gönderilmez.
• Bilinmeyen alanlar yok sayılır. Yanlış biçimdeki bir alan (geçerli olmayan bir IP adresi, saat içermeyen bir tarih) yanıtı geçersiz kılar.

Hangi İddiaya Hangi Kanıt Yanıt Verir

Chargeless bir itiraz için elindeki kanıtı, bu bölümlerden hangilerinin bulunduğuna bakarak derecelendirir (zayıf, orta, güçlü). Derece tahminle değil, sayılarak belirlenir ve itirazla birlikte kaydedilir.

Tamamı iade edilmiş bir ödeme her iddiayı yanıtlar; Chargeless bunu sağlayıcıdan öğrenir.

Visa Compelling Evidence 3.0

Visa kartla yapılan bir ödemeye dolandırıcılık itirazı geldiğinde, aynı kartla yapılmış, 120 ile 365 gün önceki ve hiç itiraz edilmemiş iki ödeme, itiraz edilen ödemeyle aynı müşteri IP adresini ya da cihazını ve bir ortak bilgiyi daha (hesap, teslimat adresi) paylaşıyorsa sorumluluk kart sahibinin bankasına geçer.

Chargeless önceki ödemeleri bulur ve prior_charges içinde sunar. Paketin gönderilebilmesi için yanıtınızda şunlar bulunmalıdır:

• itiraz edilen satın alma için purchase.ip ya da purchase.device_id (veya device_fingerprint);
• sunulan tahsilatlardan en az ikisi için prior_charges içinde, itiraz edilen satın almayla aynı IP adresine ya da cihaza ve aynı account_id değerine (veya teslimat adresine) sahip bir kayıt.

Uygunluğa ödeme sağlayıcısı karar verir. Bu bilgiler yoksa itiraz, kanıtınızın geri kalanıyla yanıtlanır.

Eksiksiz Bir Sunucu

Node.js ile, bağımlılık olmadan. İmzayı doğrular, tahsilatı bulur ve yanıtı döndürür.

import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.CHARGELESS_EVIDENCE_SECRET; // srme_…
const HOST = 'evidence.example.com';                    // as Chargeless calls it
const PATH = '/chargeless/evidence';

function verified(req, body) {
  const ts = req.headers['x-supportroute-timestamp'] ?? '';
  const sent = req.headers['x-supportroute-signature'] ?? '';
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const mac = createHmac('sha256', SECRET);
  mac.update(`${ts}\nPOST\n${HOST}\n${PATH}\n\n`);
  mac.update(body);
  const want = Buffer.from('v1=' + mac.digest('hex'));
  const got = Buffer.from(sent);
  return got.length === want.length && timingSafeEqual(got, want);
}

createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== PATH) return res.writeHead(404).end();
  const chunks = [];
  for await (const c of req) chunks.push(c);
  const body = Buffer.concat(chunks);
  if (!verified(req, body)) return res.writeHead(401).end();

  const q = JSON.parse(body);
  const answer = { request_id: q.request_id };
  if (!q.test) {
    // Your own lookups, by the provider's ids.
    const order = await orders.byPayment(q.charge.payment_ref ?? q.charge.ref);
    if (order) {
      answer.customer = { account_id: order.userId, account_created_at: order.user.createdAt };
      answer.purchase = { at: order.createdAt, ip: order.ip, device_id: order.deviceId,
        product: { name: order.plan, kind: 'subscription' } };
      answer.usage = await usage.since(order.userId, order.createdAt);   // { first_at, last_at, count, events }
      answer.cancellation = { requested: Boolean(order.cancelRequestedAt), requested_at: order.cancelRequestedAt ?? undefined };
      answer.prior_charges = await Promise.all((q.prior_charges ?? []).map(async (p) => {
        const o = await orders.byPayment(p.payment_ref ?? p.ref);
        return o && { ref: p.ref, ip: o.ip, device_id: o.deviceId, account_id: o.userId };
      })).then((list) => list.filter(Boolean));
    }
  }
  res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(answer));
}).listen(8443);

Test Etme

• Paneldeki Test İsteği Gönder: "test": true içeren imzalı bir çağrıdır; kayıtlı kimlik bilgileriniz varsa bunlar da gönderilir. URL'yi, kimlik bilgilerini, imzayı ve yanıtınızın geçerliliğini kontrol eder. Hiçbir şey kanıt olarak kullanılmaz. Ağ geçidinizden dönen bir 401 ya da 403, "Servis 200 yerine HTTP 401 ile cevap verdi." olarak görünür.
• Sözleşmedeki örnekler (schemas/merchant-evidence/examples/v1/, sözleşme zip dosyasında) geçerli istek ve yanıtlardır; signature.json ile doğrulayıcınızı test edebilirsiniz.

Panelde Gördükleriniz

Ayarlar → Kanıt Servisi sayfasında şunları görürsünüz: bir erişim token'ının kayıtlı olup olmadığı ve kendi başlıklarınızdan hangilerinin kayıtlı olduğu (değerleri asla gösterilmez); son test ve bir itiraz için yapılan son istek, her birinin nasıl sonuçlandığı (yanıtlandı, yanıt yok, sözleşmeye uymayan yanıt ve nedeni) ve günlükleriniz için istek kimliği.

Bir itirazın vakasındaki zaman çizelgesi, kanıtın ne zaman hazırlandığını ve ne zaman gönderildiğini gösterir. Kanıtın kendisi ödeme sağlayıcınızdadır: neyin gönderildiğini görmek için itirazı sağlayıcınızda açın.