API Dokümantasyonu

https://thirdparty.tahsilatmatik.com/api/v1

X-Api-Key: pk_xxx
X-Api-Secret: sk_xxx

curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/checkout/sessions \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "currency": "TRY",
    "reference": "SIPARIS-1001",
    "callback_url": "https://siteniz.com/odeme/sonuc",
    "customer": { "email": "ahmet@ornek.com", "phone": "5320000000", "code": "CARI-1001" },
    "metadata": { "order_id": 1001 }
  }'

HTTP/1.1 201 Created
{
  "token": "Hh3k...long-unguessable-token",
  "reference": "SIPARIS-1001",
  "checkout_url": "https://thirdparty.tahsilatmatik.com/checkout/Hh3k...long-unguessable-token",
  // Oturumun O ANKİ durumu: created | pending | failed.
  "status": "created",
  // checkout_url'in son geçerlilik anı (ISO-8601); süre tanımlı değilse null.
  "expires_at": "2026-08-06T10:15:00+00:00",
  // Uygulanan koşul grubu; grup gönderilmediyse ve varsayılan yoksa null.
  "condition_group": { "id": 7, "name": "Kampanya", "slug": "kampanya" }
}

curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/checkout/sessions \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "currency": "TRY",
    "reference": "SIPARIS-1001",
    "callback_url": "https://siteniz.com/odeme/sonuc",
    "condition_group_id": 7
  }'
# ── ya da slug ile: ────────────────────────────────────────────
#   "condition_group": "kampanya"
#
# İkisi de opsiyoneldir. Göndermezseniz varsayılan grup (tanımlıysa),
# o da yoksa genel koşullar (tüm taksit/komisyon/POS kuralları) uygulanır.

HTTP/1.1 200 OK
{
  "token": "Hh3k...long-unguessable-token",
  "reference": "SIPARIS-1001",
  "checkout_url": "https://thirdparty.tahsilatmatik.com/checkout/Hh3k...long-unguessable-token",
  // Oturumun O ANKİ durumu: created | pending | failed.
  "status": "failed",
  // checkout_url'in son geçerlilik anı (ISO-8601); süre tanımlı değilse null.
  "expires_at": "2026-08-06T10:15:00+00:00",
  // Uygulanan koşul grubu; grup gönderilmediyse ve varsayılan yoksa null.
  "condition_group": { "id": 7, "name": "Kampanya", "slug": "kampanya" }
}
# Aynı reference ile ikinci istek → YENİ oturum AÇILMAZ; mevcut oturum aynen
# döner (aynı token, aynı checkout_url). Gövde 201 ile BİREBİR aynıdır: iki
# durumu gövdeden değil DURUM KODUNDAN ayırın (201 = oluşturuldu, 200 = mevcut).
# status oturumun geçmişini dürüstçe gösterir — burada önceki deneme banka
# tarafından reddedilmiş (failed), oturum yine de tekrar ödenebilir.
# Süresi geçmiş oturum tazelenir, token'sız kayda token üretilir → dönen
# checkout_url DAİMA ödenebilir. Tutar ve koşul grubu DEĞİŞMEZ.

HTTP/1.1 422 Unprocessable Content
{
  "message": "Bu sipariş referansı için zaten tamamlanmış bir ödeme var.",
  "errors": {
    "reference": ["Bu sipariş referansı için zaten tamamlanmış bir ödeme var."]
  }
}
# Referans için zaten TAMAMLANMIŞ bir ödeme var (paid / authorized / refunded):
# aynı sipariş ikinci kez tahsil edilmesin diye yeni oturum açılmaz.
# Çözüm: yeni bir reference gönderin. Alan adı ve mesaj /v1/payments ve
# /v1/meal-payments ile AYNIDIR.

<!-- Ödeme sayfasını sitenize iframe olarak gömün -->
<iframe
  src="CHECKOUT_URL_BURAYA"
  width="100%" height="720"
  style="border:0; max-width:480px"
  allow="payment">
</iframe>

<!-- ya da tam sayfa yönlendirme: -->
<a href="CHECKOUT_URL_BURAYA">Ödemeye Geç</a>

HTTP/1.1 201 Created
{
  "data": {
    "id": 42,
    "reference": "SIPARIS-1001",
    "method": "card",
    "status": "paid",            // paid | pending(3D) | failed | authorized(provizyon)
    "amount": "149.90",
    "currency": "TRY",
    "installment_count": 1,
    "capture_mode": "auto",
    "net_amount": 149.90,
    "transactions": [
      { "type": "sale", "provider": "garanti", "provider_ref": "...", "status": "success" }
    ]
  }
}

curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/payments \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: SIPARIS-2001" \
  -d '{
    "reference": "SIPARIS-2001",
    "amount": 149.90,
    "currency": "TRY",
    "installment_count": 1,
    "use_3d": true,                      // ← bu işlem 3D Secure ile
    "card": { "number": "4355084355084358", "holder": "AHMET YILMAZ",
              "exp_month": "12", "exp_year": "30", "cvv": "000" },
    "callback_url": "https://siteniz.com/odeme/sonuc"
  }'

HTTP/1.1 201 Created
{
  "data": {
    "id": 51,
    "reference": "SIPARIS-2001",
    "status": "pending",                 // ← henüz tahsil EDİLMEDİ
    "amount": "149.90",
    "three_d_requested": true,           // KARAR: 3D akışı istendi
    "three_d_secure": true,              // FİİLEN: 3D akışıyla yürütülüyor
    "three_d_reason": "request",         // kararı veren katman
    "metadata": {
      "redirect_html": "<form method=\"post\" action=\"https://banka…\">…</form>"
    }
  }
}
# redirect_html'i müşterinin TARAYICISINDA render edin → banka 3D sayfası açılır.
# Kesin sonuç 3D dönüşünde callback_url'inize imzalı S2S POST ile gelir
# (payment.paid / payment.failed).

// status === "pending" → 3D Secure gerekiyor.
const meta = res.data.metadata;
if (res.data.status === "pending") {
  if (meta.redirect_html) {
    // Bankaya otomatik POST eden formu müşterinin tarayıcısında render edin:
    document.open(); document.write(meta.redirect_html); document.close();
  } else if (meta.redirect_url) {
    window.location.href = meta.redirect_url;
  }
}
// 3D bitince müşteri BİZİM sonuç ekranımızda kalır (artık sitenize otomatik
// tarayıcı yönlendirmesi YAPILMAZ, #332). Sonucu callback_url'inize gönderdiğimiz
// imzalı server-to-server POST (payment.paid / payment.failed) ile alın.

curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/payments \
  -H "X-Api-Key: pk_xxx" \
  -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: SIPARIS-2002" \
  -d '{
    "reference": "SIPARIS-2002",
    "amount": 149.90,
    "currency": "TRY",
    "installment_count": 1,
    "use_3d": false,                     // ← 3D'siz (non-secure) işlem
    "condition_group": "kampanya",       // ← opsiyonel: koşul grubu (slug)
    "card": { "number": "4355084355084358", "holder": "AHMET YILMAZ",
              "exp_month": "12", "exp_year": "30", "cvv": "000" }
  }'

HTTP/1.1 201 Created            ← sonuç SENKRON döner
{
  "data": {
    "id": 52,
    "reference": "SIPARIS-2002",
    "status": "paid",                    // tahsil edildi
    "amount": "149.90",
    "currency": "TRY",
    "installment_count": 1,
    "three_d_requested": false,          // KARAR: 3D akışı istenmedi
    "three_d_secure": false,             // FİİLEN: 3D akışı koşmadı
    "three_d_reason": "request",         // kararı veren katman (bkz. aşağıdaki tablo)
    "condition_group_id": 7,
    "condition_group": { "id": 7, "name": "Kampanya", "slug": "kampanya" },
    "paid_at": "2026-08-03T10:00:00+00:00",
    "transactions": [
      { "type": "sale", "provider": "garanti", "status": "success" }
    ]
    // metadata.redirect_html YOKTUR — yönlendirme adımı hiç oluşmaz.
  }
}

# ── Banka/kart reddederse (yine ödeme nesnesi döner): ──────────────
HTTP/1.1 402 Payment Required
{ "data": { "id": 53, "reference": "SIPARIS-2003", "status": "failed", … } }
# Ret nedeni (error_code / error_message) payment.failed bildiriminde gelir.

HTTP/1.1 422 Unprocessable Content
{
  "message": "Belirtilen ödeme koşulu grubu bulunamadı veya aktif değil.",
  "errors": {
    "condition_group": ["Belirtilen ödeme koşulu grubu bulunamadı veya aktif değil."]
  }
}
# Geçersiz/pasif grup ya da BAŞKA bir üye iş yerine ait grup id/slug → 422.
# Hata alanı adı her iki parametre için de "condition_group"tur.

HTTP/1.1 422 Unprocessable Content
{
  "message": "Belirtilen sanal POS bulunamadı veya aktif değil.",
  "errors": {
    "virtual_pos_id": ["Belirtilen sanal POS bulunamadı veya aktif değil."]
  }
}
# Bilinmeyen, PASİF ya da BAŞKA bir üye iş yerine ait id → hepsi AYNI mesaj
# (kaynak numaralandırmaya kapalı: başka işletmenin POS id'lerini tarayamazsınız).
# Hata alanı adı gönderdiğiniz parametrenin adıdır: "virtual_pos_id".
# Gövde hiçbir iç model/sınıf adı, satır kimliği veya SQL içermez.

curl "https://thirdparty.tahsilatmatik.com/api/v1/installments?amount=1000&card_brand=visa" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"

// Yanıt:
{ "data": [
  { "installment_count": 1, "card_brand": null,   "commission_rate": "0.00", "total": 1000, "monthly": 1000 },
  { "installment_count": 3, "card_brand": "visa", "commission_rate": "4.50", "total": 1045, "monthly": 348.33 }
] }

# Koşul grubuna göre taksit sorgulama (id ya da slug — biri yeterli):
curl "https://thirdparty.tahsilatmatik.com/api/v1/installments?amount=1000&card_brand=visa&condition_group=kampanya" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"

curl "https://thirdparty.tahsilatmatik.com/api/v1/installments?amount=1000&condition_group_id=7" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"

# Göndermezseniz: varsayılan grup (tanımlıysa) → o da yoksa genel koşullar.
# Geçersiz/başka üye iş yerine ait grup → 422 ("condition_group").

curl "https://thirdparty.tahsilatmatik.com/api/v1/payments/SIPARIS-1001" \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx"
// → PaymentResource (status: paid | pending | failed | authorized | refunded)

# Tam iade: body boş. Kısmi iade: "amount" gönderin.
curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/payments/SIPARIS-1001/refund \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50.00 }'

# Provizyon (ön provizyon): tutarı blokede tut, sonra kapat.
curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/payments \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500, "pre_auth": true, "card": { ... } }'
# → data.status = "authorized" (henüz tahsil edilmedi).
# Provizyon kapama / iptal: panel > Ödemeler ekranı
# ("Provizyonu Kapat" / "Provizyonu İptal Et").

# Bakiye sorgu
curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/meal-payments/balance \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "meal_card_id": 1, "card": { "number": "6060...." } }'

# Ödeme (Multinet / Sodexo-Pluxee / Edenred-Ticket / Setcard / Metropol)
curl -X POST https://thirdparty.tahsilatmatik.com/api/v1/meal-payments \
  -H "X-Api-Key: pk_xxx" -H "X-Api-Secret: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "meal_card_id": 1, "amount": 80, "reference": "SIP-1002",
        "card": { "number": "6060....", "pin": "1234" } }'

POST https://siteniz.com/webhook
X-Tahsilatmatik-Signature: t=1717500000,v1=9f86d08...   (HMAC-SHA256)
X-Tahsilatmatik-Event:     payment.paid
X-Tahsilatmatik-Delivery:  12345                        (tekilleştirme id'si)

{
  "id": 12345,                                  // id + created_at retry'larda SABİT
  "event": "payment.paid",                      //   → aynı teslimatı idempotent ayıklayın
  "created_at": "2026-06-05T10:00:00+00:00",
  "data": {
    "reference": "SIPARIS-1001",
    "status": "paid",
    "amount": 149.90,
    "refunded_amount": 0,
    "currency": "TRY",
    "installment_count": 1,
    "method": "card",
    "paid_at": "2026-06-05T10:00:00+00:00",
    "transaction_id": 84,                        // opsiyonel (son işlem kimliği)
    "metadata": { "order_id": 1001 }
  }
}

"event": "payment.failed",
"data": {
  "reference": "SIPARIS-1001",
  "status": "failed",
  "amount": 149.90,
  ...
  "error_code": "51",
  "error_message": "Yetersiz bakiye"
}

<?php
// İmza doğrulama (PHP) — secret webhook endpoint'i oluştururken bir kez gösterilir.
$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_TAHSILATMATIK_SIGNATURE'] ?? '';
$secret  = 'whsec_xxx';   // endpoint'in kendi secret'i

parse_str(str_replace(',', '&', $header), $p);   // t=..., v1=...
$expected = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $payload, $secret);

if (! hash_equals($expected, $p['v1'] ?? '') || abs(time() - (int)($p['t'] ?? 0)) > 300) {
    http_response_code(400); exit('invalid signature');
}
$event = json_decode($payload, true);
// $event['id'] ile tekilleştirin, sonra 2xx dönün.
http_response_code(200);

POST https://siteniz.com/odeme/sonuc          (checkout callback_url)
X-Tahsilatmatik-Signature: t=1717500000,v1=4b2a9c...
X-Tahsilatmatik-Event:     payment.paid
X-Tahsilatmatik-Delivery:  12346
X-Tahsilatmatik-Key:       pk_xxx     (imza anahtarının türetildiği API anahtarı)

{
  "id": 12346,
  "event": "payment.paid",              // yalnız paid | authorized | failed
  "created_at": "2026-06-05T10:00:00+00:00",
  "data": {
    "reference": "SIPARIS-1001",        // eski GET dönüşündeki reference + status
    "status": "paid",                   //   anahtarları burada da mevcuttur
    "amount": 149.90,
    "refunded_amount": 0,
    "currency": "TRY",
    "installment_count": 1,
    "method": "card",
    "paid_at": "2026-06-05T10:00:00+00:00",
    "metadata": { "order_id": 1001 }
  }
}

signingKey = HMAC_SHA256("posaxi:callback_url:v1", sha256_hex(sk_...))

<?php
// callback_url imza doğrulama (PHP). Kayıtlı webhook'tan farkı: bu adresin kendine
// ait bir secret'i YOKTUR; imza anahtarını KENDİ API secret'inizden (sk_...) türetin.
$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_TAHSILATMATIK_SIGNATURE'] ?? '';
$keyId   = $_SERVER['HTTP_X_TAHSILATMATIK_KEY'] ?? '';   // hangi pk_ kullanıldı

// X-Tahsilatmatik-Key (pk_...) ile eşleşen API anahtarınızın gizli secret'i:
$apiSecret = 'sk_xxx';

// Türev imza anahtarı — backend ile birebir aynı reçete:
$signingKey = hash_hmac('sha256', 'posaxi:callback_url:v1', hash('sha256', $apiSecret));

parse_str(str_replace(',', '&', $sig), $p);   // t=..., v1=...
$expected = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $payload, $signingKey);

if (! hash_equals($expected, $p['v1'] ?? '') || abs(time() - (int)($p['t'] ?? 0)) > 300) {
    http_response_code(400); exit('invalid signature');
}
// $event['id'] ile tekilleştirin, sonra 2xx dönün (aksi halde tekrar denenir).
http_response_code(200);

HTTP/1.1 422 Unprocessable Content
{
  "message": "Tutar alanı zorunludur.",
  "errors": {
    "amount": ["Tutar alanı zorunludur."]
  }
}
# "errors" anahtarları GÖNDERDİĞİNİZ alan adlarıdır (amount, virtual_pos_id,
# condition_group, meal_card_id, reference …). Mesaj dili X-Locale başlığına
# göre döner; varsayılan Türkçe'dir.

HTTP/1.1 404 Not Found
{ "message": "Kayıt bulunamadı." }
# Örn. GET /v1/payments/BILINMEYEN-REF. Eski ham framework metni
# ("No query results for model [App\Models\Payment] BILINMEYEN-REF")
# artık DÖNMEZ — iç model adı ve satır kimliği sızdırılmaz.