GeliştiricilerAPI v1.1

Ödesin Geliştirici Merkezi

Ödeme oturumları, kart ve havale entegrasyonları, webhook bildirimleri ve kod örnekleri — mağazanızı Ödesin'e bağlamak için tek referans.

x-api-key

Ne bulabilirsiniz

  • Canlı API referansı
  • Hosted & whitelabel akışlar
  • Webhook akışı

Base URL

https://odesin.com

Protokol

HTTPS / REST

Format

JSON

Sanal POS (Hosted) modelinde ödeme oturumunu siz API ile oluşturursunuz; tahsilat işlemi banka sanal POS altyapısı üzerinden 3D Secure ile güvenli şekilde işlenir. Müşteri kart bilgilerini checkout_url ile verdiğimiz Ödesin checkout sayfasında girer — bu adresi doğrudan yönlendirme ile açabilir veya kendi sitenizde <iframe> içinde gösterebilirsiniz. Kart verisi mağaza sistemlerinize uğramaz, doğrudan bankaya iletilir. Ödeme sonucunda müşteri return_url adresinize döner; isteğe bağlı callback_url ile sunucunuza webhook bildirimi gönderilir.

Genel Bakış

Tüm API isteklerinde x-api-key ile kimlik doğrulaması yapılır. Mağazanızda Sanal POS etkin olmalıdır; aksi halde 403 döner.

  • POST /api/payment/create-session ile mode: "card" gönderilir.
  • Yanıttaki checkout_url müşterinin ödeme ekranıdır; yönlendirme veya iframe ile açılır.
  • Ödeme başarılı veya başarısız olduğunda müşteri return_url adresinize otomatik yönlendirilir (5 saniyelik geri sayım ve "Mağazaya Dön" butonu ile). URL'e odesin_payment=success|failed ve odesin_ref=ISLEM_NO query parametreleri eklenir.
Kart verisi yalnızca Ödesin checkout akışında toplanır ve 3D Secure üzerinden bankaya iletilir; mağaza tarafında kart saklamaz veya işlemezsiniz. 3D Secure doğrulaması gerektiğinde müşteri banka doğrulama sayfasına yönlendirilir, doğrulama sonrası ödeme otomatik tamamlanır.

Kart oturumu oluştur

İstek POST /api/payment/create-session endpoint'ine gider. Kart modunda return_url zorunludur; diğer alanlar aşağıdaki tabloda özetlenmiştir.

AlanZorunluAçıklama
modeEvet"card"
amountEvetTutar (TRY)
return_urlEvetÖdeme tamamlandıktan sonra müşterinin döneceği HTTPS adresi
callback_urlHayırMağaza webhook URL'i; yoksa mağaza ayarındaki webhook kullanılır. Başarılı kart ödemesinde payment.approved benzeri bildirim gönderilir.
customer_nameEvetMüşteri adı soyadı
customer_emailEvetMüşteri e-posta adresi
customer_phoneEvetMüşteri telefon numarası
descriptionHayırSipariş / açıklama metni
curl -X POST https://odesin.com/api/payment/create-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_XXXXXXXXXXXX" \
  -d '{
    "mode": "card",
    "amount": 199.90,
    "return_url": "https://magazaniz.com/siparis/tesekkur",
    "callback_url": "https://magazaniz.com/api/odesin-webhook",
    "customer_name": "Ali Veli",
    "customer_email": "ali@email.com",
    "customer_phone": "05321234567",
    "description": "Sipariş #4521"
  }'

Örnek yanıt

{
  "session_id": "uuid",
  "mode": "card",
  "checkout_url": "https://odesin.com/checkout/uuid",
  "reference_code": "ODSN-XXXX",
  "amount": 199.9,
  "currency": "TRY",
  "expires_at": "2025-01-01T12:00:00.000Z"
}

Checkout ve 3D Secure

Müşteri checkout_url üzerindeki Ödesin checkout sayfasında kart bilgilerini (PAN, SKT, CVV) girer. Form gönderildiğinde Ödesin sunucusu kart verisini banka sanal POS altyapısı üzerinden 3D Secure akışına sokar.

Akış

  1. Müşteri Ödesin checkout sayfasında kartını girer ve "Öde" butonuna tıklar.
  2. Ödesin, kart verisi ile gt3dengine formunu oluşturup bankaya POST eder (3D_PAY).
  3. Banka, müşterinin tarayıcısını 3D Secure doğrulama sayfasına yönlendirir (SMS / mobil onay).
  4. Doğrulama sonrası banka, Ödesin callback adresine (/api/payment/garanti/callback) sonucu POST eder.
  5. Oturum durumu paid veya failed olur; müşteri her iki durumda da return_url adresinize otomatik yönlendirilir (?odesin_payment=success|failed&odesin_ref=ISLEM_NO).
Kart verisi yalnızca Ödesin checkout sayfasında toplanır ve doğrudan bankaya iletilir; mağaza sunucunuz kart numarası veya CVV görmez. 3D Secure doğrulaması banka tarafında yapılır.
Checkout sayfasını iframe içinde gösterirken, çerçeve ve üst sayfa kaynağının güvenilir olduğundan emin olun (ör. yalnızca kendi domain'inizden embed). Bazı bankalar iframe içinde 3D doğrulama sayfasını engelleyebilir; bu durumda tam sayfa yönlendirme (window.location.href) önerilir.

Dönüş ve webhook

Ödeme sonrası (başarılı veya başarısız) müşteri return_url adresinize otomatik yönlendirilir. URL'e eklenen query parametreleri ile ödeme durumunu anlık kontrol edebilirsiniz:

ParametreDeğerAçıklama
odesin_paymentsuccess / failedÖdeme sonucu
odesin_refMetinİşlem no (session ID kısaltması)
odesin_detailMetinBanka hata mesajı (red durumunda)
odesin_hash_ok1 / 0Banka yanıt hash doğrulaması

Sunucu tarafında, oturum oluştururken verdiğiniz callback_url veya mağaza panelinde tanımlı webhook adresine JSON bildirim gönderilir:

{
  "event": "payment.approved",
  "session_id": "uuid",
  "reference_code": "ODSN-XXXX",
  "amount": 199.9,
  "currency": "TRY",
  "status": "paid",
  "transaction_id": "uuid",
  "payment_method": "card",
  "provider": "bank_pos",
  "timestamp": "2025-01-01T12:00:00.000Z"
}
Webhook URL'inizin HTTPS ve erişilebilir olduğundan emin olun. Yanıtta dönen reference_code ve session_id ile kendi sisteminizde mutabakat yapın. Ödeme başarısız olduğunda olay tipi payment.rejected olur.

Kod örnekleri

JavaScriptOturum oluştur ve müşteriyi checkout'a yönlendir

const BASE = "https://odesin.com";
const API_KEY = "sk_live_XXXXXXXXXXXX";

async function startHostedCardCheckout(order) {
  const res = await fetch(`${BASE}/api/payment/create-session`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
    },
    body: JSON.stringify({
      mode: "card",
      amount: order.total,
      currency: "TRY",
      return_url: order.successUrl,
      callback_url: order.webhookUrl,
      customer_name: order.customerName,
      customer_email: order.customerEmail,
      customer_phone: order.customerPhone,
      description: order.description ?? "",
    }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error ?? res.statusText);
  // Tarayıcı: tam sayfa yönlendirme veya iframe src = data.checkout_url
  window.location.href = data.checkout_url;
}

// Örnek: startHostedCardCheckout({ total: 199.9, successUrl: "https://...", webhookUrl: "https://...", customerName: "Ali" });

Pythoncreate-session (kart / hosted)

import requests

BASE = "https://odesin.com"
API_KEY = "sk_live_XXXXXXXXXXXX"
headers = {"Content-Type": "application/json", "x-api-key": API_KEY}

r = requests.post(f"{BASE}/api/payment/create-session", headers=headers, json={
    "mode": "card",
    "amount": 199.90,
    "return_url": "https://magazaniz.com/tesekkur",
    "callback_url": "https://magazaniz.com/api/webhook",
    "customer_name": "Ali Veli",
    "customer_email": "ali@email.com",
    "customer_phone": "05321234567",
})
r.raise_for_status()
data = r.json()
checkout_url = data["checkout_url"]  # Müşteriye bu adresi açın

PHPcreate-session (kart / hosted)

<?php
$base = "https://odesin.com";
$apiKey = getenv('ODESIN_API_KEY') ?: '';

$payload = [
    'mode' => 'card',
    'amount' => 199.90,
    'currency' => 'TRY',
    'return_url' => 'https://magazaniz.com/tesekkur',
    'callback_url' => 'https://magazaniz.com/api/webhook',
    'customer_name' => 'Ali Veli',
    'customer_email' => 'ali@email.com',
    'customer_phone' => '05321234567',
    'description' => 'Sipariş #4521',
];
$ch = curl_init($base . '/api/payment/create-session');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-api-key: ' . $apiKey,
    ],
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
// header('Location: ' . $data['checkout_url']); exit;
Kart girişi ve 3DS yönlendirmesi checkout_url üzerindeki Ödesin sayfasında tamamlanır; sunucunuz kart PAN/CVV görmez.

Sık görülen hatalar

HTTPDurum
403Mağazada Sanal POS kapalı (pos_enabled)
400mode: "card" iken return_url eksik veya geçersiz gövde
401API anahtarı eksik veya geçersiz
402 / 409 / 410Kart reddi, oturum uygun değil veya süre dolmuş