OdemeNet API

Hosted Page API Dokümantasyonu

Müşterilerin kart bilgilerini güvenli bir şekilde girebilecekleri ödeme sayfası oluşturma
Genel Bakış

OdemeNet Hosted Page API, müşterilerinizin kart bilgilerini güvenli bir iframe veya yeni sekmede girebilecekleri bir ödeme sayfası URL'i oluşturmanızı sağlar. Kart bilgileri sizin sunucunuzdan geçmez, doğrudan güvenli ödeme sayfasında işlenir.

Önemli: Tüm API çağrıları için geçerli bir JWT token gereklidir. Authorization header'ında Bearer token kullanın.
Özellikler:
  • PCI-DSS Uyumlu: Kart bilgileri sizin sunucunuzdan geçmez
  • Kolay Entegrasyon: Tek bir API çağrısı ile hosted page URL'i alın
  • Güvenli Token: Her sayfa için benzersiz ve güvenli token üretilir
  • İframe Desteği: Sayfanızda iframe olarak gösterebilirsiniz
  • Müşteri Bilgileri: İsteğe bağlı müşteri bilgileri ekleyebilirsiniz
  • Ürün Desteği: Ödemeye ait ürün bilgilerini ekleyebilirsiniz
  • Otomatik Yönlendirme: Başarılı/başarısız ödeme sonrası özel URL'lere yönlendirme
Hosted Page Oluşturma API
Endpoint Bilgileri
Method POST
URL /api/Payment/hostedpage
Authorization Bearer {token}
Content-Type application/json
Zorunlu Request Parametreleri
Parametre Tip Açıklama
Amount decimal Ödeme tutarı (0'dan büyük olmalı)
OrderNumber string Sipariş numarası (benzersiz olmalı)
Opsiyonel Request Parametreleri
Parametre Tip Varsayılan Açıklama
Currency string "TRY" Para birimi kodu
CurrencyId int? 1 Para birimi ID
Installment int 1 Taksit sayısı
ClientIp string null Müşteri IP adresi
Phone string null Müşteri telefon numarası
SuccessUrl string null Başarılı ödeme sonrası yönlendirilecek URL
FailUrl string null Başarısız ödeme sonrası yönlendirilecek URL
CardAlias string null Kart takma adı
MerchantUniqueCode string null Merchant benzersiz kodu
TrackingCode string null İzleme kodu
Half3D bool? false Yarım 3D güvenlik kullanımı
Customer object null Müşteri bilgileri objesi (opsiyonel)
BillingAddress object null Fatura adresi bilgileri (opsiyonel)
ShippingAddress object null Teslimat adresi bilgileri (opsiyonel)
Products array null Ürün listesi (opsiyonel)
Customer Objesi Parametreleri (Opsiyonel)
Parametre Tip Açıklama
FullName string Müşteri adı soyadı
Phone string Telefon numarası
Email string E-posta adresi
Country string Ülke
City string Şehir
Address string Adres
IdentityNumber string TC Kimlik No
TaxNumber string Vergi numarası
BillingAddress Objesi Parametreleri (Opsiyonel)
Parametre Tip Açıklama
Name string Fatura adı
City string Şehir
Country string Ülke
Address string Adres
ZipCode string Posta kodu
ShippingAddress Objesi Parametreleri (Opsiyonel)
Parametre Tip Açıklama
Name string Teslimat adı
City string Şehir
Country string Ülke
Address string Adres
ZipCode string Posta kodu
Products Array Parametreleri (Opsiyonel)
Parametre Tip Açıklama
Id string Ürün ID
Name string Ürün adı
Category string Ürün kategorisi
Description string Ürün açıklaması
Amount decimal Ürün tutarı
Basit Request Örneği
JSON 
{
  "Amount": 250.00,
  "Currency": "TRY",
  "Installment": 1,
  "OrderNumber": "ORD-2024-12345",
  "SuccessUrl": "https://example.com/payment/success",
  "FailUrl": "https://example.com/payment/fail"
}
Tam Detaylı Request Örneği
JSON 
{
  "Amount": 450.00,
  "Currency": "TRY",
  "CurrencyId": 1,
  "Installment": 3,
  "OrderNumber": "ORD-2024-12346",
  "ClientIp": "192.168.1.100",
  "Phone": "+905551234567",
  "SuccessUrl": "https://example.com/payment/success",
  "FailUrl": "https://example.com/payment/fail",
  "CardAlias": "İş Kartım",
  "MerchantUniqueCode": "MERCHANT-001",
  "TrackingCode": "TRACK-12345",
  "Half3D": false,
  "Customer": {
    "FullName": "Ahmet Yılmaz",
    "Phone": "+905551234567",
    "Email": "ahmet@example.com",
    "Country": "Türkiye",
    "City": "İstanbul",
    "Address": "Kadıköy Mah. Bahariye Cad. No:25",
    "IdentityNumber": "12345678901",
    "TaxNumber": "1234567890"
  },
  "BillingAddress": {
    "Name": "Ahmet Yılmaz",
    "City": "İstanbul",
    "Country": "Türkiye",
    "Address": "Kadıköy Mah. Bahariye Cad. No:25 Daire:5",
    "ZipCode": "34710"
  },
  "ShippingAddress": {
    "Name": "Mehmet Demir",
    "City": "Ankara",
    "Country": "Türkiye",
    "Address": "Çankaya Mah. Atatürk Bulvarı No:100",
    "ZipCode": "06100"
  },
  "Products": [
    {
      "Id": "PROD-001",
      "Name": "Kablosuz Kulaklık",
      "Category": "Elektronik",
      "Description": "Bluetooth 5.0 Kulaklık - Siyah",
      "Amount": 250.00
    },
    {
      "Id": "PROD-002",
      "Name": "Telefon Kılıfı",
      "Category": "Aksesuar",
      "Description": "Silikon Kılıf - Mavi",
      "Amount": 200.00
    }
  ]
}
Not:
  • Customer: Opsiyonel - Müşteri bilgilerini kaydetmek için kullanın
  • BillingAddress: Opsiyonel - Fatura adresi bilgilerini kaydetmek için kullanın
  • ShippingAddress: Opsiyonel - Teslimat adresi bilgilerini kaydetmek için kullanın
  • Products: Opsiyonel - Ancak kullanılıyorsa, tüm ürün tutarlarının toplamı Amount ile eşleşmelidir
Başarılı Response
JSON 
{
  "Success": true,
  "Message": "Hosted page başarıyla oluşturuldu",
  "Data": {
    "Url": "https://api.odemenet.com/iframe/HST-152-SGh...",
    "Token": "HST-152-SGhnbC1UdWltUGNCNVRw...",
    "ExpireDate": "2024-01-27T10:30:00"
  },
  "TransactionId": "123e4567-e89b-12d3-a456-426614174000",
  "PaymentReferenceNumber": "ON-847562391",
  "BankName": "Garanti BBVA",
  "Customer": {
    "Id": "456e4567-e89b-12d3-a456-426614174001",
    "FullName": "Ahmet Yılmaz",
    "Email": "ahmet@example.com"
  }
}
Response Alanları Açıklaması
Alan Tip Açıklama
Success boolean İşlem başarı durumu
Message string İşlem mesajı
Data.Url string Ödeme sayfası URL'i (iframe veya yeni sekme)
Data.Token string Güvenlik token'ı
Data.ExpireDate string Token geçerlilik süresi (24 saat)
TransactionId guid İşlem ID
PaymentReferenceNumber string Ödeme referans numarası
BankName string Kullanılacak banka adı
Hata Response
JSON 
{
  "Success": false,
  "Message": "Company bulunamadı veya pasif durumda",
  "ErrorCode": "COMPANY_INACTIVE"
}
Hata Kodları ve Mesajları
Hata Kodu Mesaj Açıklama Çözüm
INVALID_REQUEST Geçersiz ödeme verisi Request body boş veya geçersiz Request formatını kontrol edin
AUTH_ERROR CompanyId claim bulunamadı JWT token geçersiz veya eksik Geçerli bir Bearer token kullanın
COMPANY_INACTIVE Company bulunamadı veya pasif durumda Firma bulunamadı veya pasif Firma durumunu kontrol edin
NO_ACTIVE_BANK Company için aktif banka bulunamadı Firma için aktif banka yok Firma banka ayarlarını yapılandırın
BANK_NOT_FOUND Seçilen banka bulunamadı Seçilen banka bulunamadı Banka tanımlarını kontrol edin
INTERNAL_ERROR Hosted page işlemi sırasında hata oluştu Sunucu hatası Tekrar deneyin veya destek alın
İşlem Akışı
  1. API Çağrısı: /api/Payment/hostedpage endpoint'ine POST isteği gönderin
  2. URL Alma: Response'dan Url ve Token bilgilerini alın
  3. Sayfa Gösterimi: URL'i iframe içinde veya yeni sekmede gösterin
  4. Ödeme İşlemi: Müşteri kart bilgilerini güvenli sayfada girer
  5. Sonuç: Ödeme tamamlandıktan sonra SuccessUrl veya FailUrl'e yönlendirilir
Kod Örnekleri
C# HttpClient 
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", token);

var hostedPageData = new
{
    Amount = 250.00m,
    Currency = "TRY",
    Installment = 1,
    OrderNumber = "ORD-2024-12345",
    SuccessUrl = "https://example.com/payment/success",
    FailUrl = "https://example.com/payment/fail",
    Customer = new
    {
        FullName = "Ahmet Yılmaz",
        Phone = "+905551234567",
        Email = "ahmet@example.com"
    }
};

var json = JsonSerializer.Serialize(hostedPageData);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.odemenet.com/api/Payment/hostedpage", content);
var result = await response.Content.ReadAsStringAsync();
var hostedPageResponse = JsonSerializer.Deserialize(result);

// Iframe veya yeni sekmede göster
Console.WriteLine($"Payment URL: {hostedPageResponse.Data.Url}");
JavaScript Fetch + Iframe 
const hostedPageData = {
    Amount: 250.00,
    Currency: 'TRY',
    Installment: 1,
    OrderNumber: 'ORD-2024-12345',
    SuccessUrl: 'https://example.com/payment/success',
    FailUrl: 'https://example.com/payment/fail',
    Customer: {
        FullName: 'Ahmet Yılmaz',
        Phone: '+905551234567',
        Email: 'ahmet@example.com'
    }
};

fetch('https://api.odemenet.com/api/Payment/hostedpage', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(hostedPageData)
})
.then(response => response.json())
.then(data => {
    if (data.Success) {
        // Iframe içinde göster
        const iframe = document.getElementById('payment-iframe');
        iframe.src = data.Data.Url;
        
        // Veya yeni sekmede aç
        // window.open(data.Data.Url, '_blank');
    } else {
        console.error('Error:', data.Message);
    }
});
Python Requests 
import requests

hosted_page_data = {
    "Amount": 250.00,
    "Currency": "TRY",
    "Installment": 1,
    "OrderNumber": "ORD-2024-12345",
    "SuccessUrl": "https://example.com/payment/success",
    "FailUrl": "https://example.com/payment/fail",
    "Customer": {
        "FullName": "Ahmet Yılmaz",
        "Phone": "+905551234567",
        "Email": "ahmet@example.com"
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

response = requests.post(
    "https://api.odemenet.com/api/Payment/hostedpage",
    json=hosted_page_data,
    headers=headers
)

data = response.json()
if data["Success"]:
    print(f"Payment URL: {data['Data']['Url']}")
    # URL'i kullanıcıya göster (iframe veya redirect)
else:
    print(f"Error: {data['Message']}")
cURL 
curl -X POST "https://api.odemenet.com/api/Payment/hostedpage" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "Amount": 250.00,
    "Currency": "TRY",
    "Installment": 1,
    "OrderNumber": "ORD-2024-12345",
    "SuccessUrl": "https://example.com/payment/success",
    "FailUrl": "https://example.com/payment/fail",
    "Customer": {
      "FullName": "Ahmet Yılmaz",
      "Phone": "+905551234567",
      "Email": "ahmet@example.com"
    }
  }'
Kullanım Senaryoları
  • E-Ticaret: Checkout sayfasında iframe ile ödeme formu gösterin
  • Abonelik: Üyelik yenileme işlemlerinde kullanın
  • B2B Ödemeler: Kurumsal ödemeler için güvenli sayfa sağlayın
  • Mobil Uygulama: WebView içinde ödeme sayfası açın
  • PCI-DSS Uyumlu: Kart bilgileri sizden geçmeden işlem yapın
Güvenlik Notları
  • Kart bilgileri hiçbir zaman sizin sunucunuzdan geçmez
  • Tüm ödeme formu SSL/TLS ile şifrelenir
  • Her sayfa için benzersiz ve güvenli token oluşturulur
  • Token 24 saat geçerlidir, sonrasında otomatik olarak devre dışı kalır
  • PCI-DSS Level 1 uyumludur
  • Bearer token mutlaka güvenli bir şekilde saklanmalıdır

2024 - 2025 © OdemeNet API Documentation. All Right Reserved

Payment Gateway API Documentation