Ö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.
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-sessionilemode: "card"gönderilir.- Yanıttaki
checkout_urlmüş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_urladresinize otomatik yönlendirilir (5 saniyelik geri sayım ve "Mağazaya Dön" butonu ile). URL'eodesin_payment=success|failedveodesin_ref=ISLEM_NOquery parametreleri eklenir.
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.
| Alan | Zorunlu | Açıklama |
|---|---|---|
| mode | Evet | "card" |
| amount | Evet | Tutar (TRY) |
| return_url | Evet | Ödeme tamamlandıktan sonra müşterinin döneceği HTTPS adresi |
| callback_url | Hayır | Mağ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_name | Evet | Müşteri adı soyadı |
| customer_email | Evet | Müşteri e-posta adresi |
| customer_phone | Evet | Müşteri telefon numarası |
| description | Hayır | Sipariş / 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ış
- Müşteri Ödesin checkout sayfasında kartını girer ve "Öde" butonuna tıklar.
- Ödesin, kart verisi ile
gt3dengineformunu oluşturup bankaya POST eder (3D_PAY). - Banka, müşterinin tarayıcısını 3D Secure doğrulama sayfasına yönlendirir (SMS / mobil onay).
- Doğrulama sonrası banka, Ödesin callback adresine (
/api/payment/garanti/callback) sonucu POST eder. - Oturum durumu
paidveyafailedolur; müşteri her iki durumda dareturn_urladresinize otomatik yönlendirilir (?odesin_payment=success|failed&odesin_ref=ISLEM_NO).
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:
| Parametre | Değer | Açıklama |
|---|---|---|
| odesin_payment | success / failed | Ödeme sonucu |
| odesin_ref | Metin | İşlem no (session ID kısaltması) |
| odesin_detail | Metin | Banka hata mesajı (red durumunda) |
| odesin_hash_ok | 1 / 0 | Banka 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"
}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çınPHPcreate-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;checkout_url üzerindeki Ödesin sayfasında tamamlanır; sunucunuz kart PAN/CVV görmez.Sık görülen hatalar
| HTTP | Durum |
|---|---|
| 403 | Mağazada Sanal POS kapalı (pos_enabled) |
| 400 | mode: "card" iken return_url eksik veya geçersiz gövde |
| 401 | API anahtarı eksik veya geçersiz |
| 402 / 409 / 410 | Kart reddi, oturum uygun değil veya süre dolmuş |