Genel API Bilgileri

Dönüş Formatları

ÖderoPay API'nin dönüş parametreleri, işlemin başarılı gerçekleşip gerçekleşmemesine ve tekil ya da çoğul sonuç değeri dönmesine göre farklılıklar içerse de, bunlar kendi içlerinde ortak birer çatı kullanır.

Hatalı İşlemler

Sistemsel ya da kurgusal bir hata gerçekleştiğinde kullanılan dönüş formatıdır. Sadece içerisinde hata bilgilerini barındıran errors isimli bir alan içerir.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
errors Error Evet Gerçekleşen hataya ilişkin bilgiler içerir. Detaylı bilgi için bkz. Ödeme Hata Kodları

Başarılı İşlemler

Başarılı işlemler sonucunda dönen cevaplar, işlem sonucunun tekil ya da çoğul olmasına göre farklı parametreler içerir.

Tekil Sonuçlu İşlemler

Ödeme alma, bir ödemeyi iade etme, alıcı oluşturma, üye işyeri detayı görüntüleme gibi tekil sonuç üreten işlem ya da sorgular için kullanılan dönüş formatıdır. Sadece içerisinde işlem sonucunu barındıran data isimli bir alan içerir.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
data any Hayır Gerçekleştirilen işlem ya da sorgu sonucu. Nitelik ve içeriği ilgili işlem ya da sorguya ilişkin dokümantasyon sayfasında detaylandırılmıştır

Çoğul Sonuçlu İşlemler

Arama ya da listeleme gibi çoğul sonuç üretme potansiyeline sahip işlem ya da sorgular sonucunda dönülen cevap formatıdır.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
items any[] Evet İşlem ya da sorgu sonucunda ulaşılan sonuçları içerir. Sonuçların nitelik ve içerikleri ilgili işlem ya da sorguya ilişkin dokümantasyon sayfasında detaylandırılmıştır
totalSize long Hayır Arama ya da listeleme gibi sayfalama niteliğine sahip işlemler sonucunda döner. Sorgu sonucunda ulaşılan toplam sonuç sayısını ifade eder. Hatalı işlemlerin dönüşlerinde bu alan yer almaz
size long Hayır Arama ya da listeleme gibi sayfalama niteliğine sahip işlemler sonucunda döner. Sorgulamada sayfa başına dönmesi istenen sonuç sayısını ifade eder. Hatalı işlemlerin dönüşlerinde bu alan yer almaz

Sonuçsuz İşlemler

Saklı kart silme gibi sonuç üretmeyen işlemler sonucunda boş cevap dönülebilir. Bu gibi işlemler oldukça nadir olmakla beraber, silme işlemlerinde bir cevap dönülmeyeceği beklentisiyle hareket edilmesi önerilir. Öte yandan, bu cevaplar 204 No Content HTTP koduyla dönülebileceği ve bu kod da başarılı işlemleri ifade ettiği için, isteğin başarılı olup olmadığı kontrolü yapılırken statü kodunun sadece 200 OK olmasına bakılması önerilmez.

Sabitler ve Enum Değerleri

Farklı işlemlerin istek ve dönüş parametreleri olarak kullanılan birtakım sabitler ve enum değerleri bu başlık altında listelenmiştir.

Para Birimleri

Değer Açıklama
TRY Türk Lirası
AZN Azerbaycan Manatı

NOT: Faaliyet gösterilen ülkeye bağlı olarak bağlı olarak para birimlerini kullanmanız gerekir. Örneğin, Azerbaycan tüccarıysanız istekleri AZN olarak göndermeniz gerekir; Türkiye merkezli iseniz TRY kullanacaksınız.

Kart Tipleri

Değer Açıklama
CREDIT_CARD Kredi kartı
DEBIT_CARD Debit kart
PREPAID_CARD Prepaid kart

Kart Kuruluşları

Değer Açıklama
VISA Visa
MASTER_CARD Master Card
AMEX American Express
TROY Troy

Alt Üye İşyeri Tipleri

Değer Açıklama
PRIVATE_COMPANY Şahıs Şirketi
LIMITED_OR_JOINT_STOCK_COMPANY LLimited ya da Anonim Şirket

Ödeme Tipleri

Değer Açıklama
CARD_PAYMENT Tamamı karttan tahsil edilen ödeme
DEPOSIT_PAYMENT Karttan para yükleme ödemesi
WALLET_PAYMENT Tamamı cüzdandan tahsil edilen ödeme
CARD_AND_WALLET_PAYMENT Bir kısmı karttan, bir kısmı cüzdandan tahsil edilen ödeme
BANK_TRANSFER Havale/EFT ödemesi

Ödeme Grupları

Değer Açıklama
PRODUCT Ürün
LISTING_OR_SUBSCRIPTION İlan, hizmet ya da abonelik
SUBSCRIPTION Tekrarlı ödeme

Ödeme Durumları

Değer Açıklama
FAILURE Ödeme başarısız
SUCCESS Ödeme başarılı
INIT_THREEDS 3D Secure başlatıldı
CALLBACK_THREEDS 3D Secure callback aşamasında

MD Status

3D Secure ile yapılan ödemelerde doğrulama sonrası banka tarafından ÖderoPay API'ye iletilen sayısal değerlerdir. Bankalar ve ödeme kuruluşları kimi zaman kendilerine özgü MD Status değerleri dönse de aşağıdaki tabloda yer alan değerler standart kabul edilebilir

Değer Açıklama
0 3D Secure imzası ya da doğrulama kodu geçersiz
1 Doğrulama başarılı
2 Kart sahibi ya da bankası sisteme kayıtlı değil
3 Kart bankası sisteme kayıtlı değil
4 Doğrulama hatası, kart sahibi sisteme daha sonra kayıt olmayı seçmiş
5 Doğrulama hatası
6 3D Secure hatası
7 Sistemsel hatası

İade Tipleri

Değer Açıklama
CARD Karta
WALLET Cüzdana

Para Gönderimi Durumları

Değer Açıklama
WAITING_FOR_APPROVAL Para gönderimi için onay bekleniyor
APPROVED Para gönderimi onaylanmış
PAYOUT_STARTED Para gönderimi başlamış

Signature Hesaplama

ÖderoPay API'lerine doğrudan yapılacak her istekte, üye işyeri hesabının erişim anahtarları kullanılarak bir kimlik doğrulaması yapılması gerekmektedir. Üye iş yerine ait erişim anahtarları bilgisine Merchant Panel üzerinden ulaşabilirsiniz.

Eğer ÖderoPay Client kullanıyorsanız erişim anahtarları bilgisini ÖderoPay objesine parametre olarak vermeniz yeterli olacaktır. Eğer client kullanmıyorsanız aşağıdaki işlemlerin gerçekleştirilmesi zorunludur.

Üye işyeri hesabınızla birlikte kimlik doğrulaması yapmak için API Gateway'e yapacağınız her istekte aşağıdaki header'ları göndermeniz gerekmektedir:

Header Adı Açıklama
x-api-key AAPI erişim anahtarı
x-rnd-key İsteğe özel oluşturulmuş rastgele bir string değer
x-auth-version Kimlik doğrulama algoritmasınin versiyon numarası. Hangi değeri vermeniz gerektiğinden emin değilseniz V1 verebilirsiniz
x-signature Yukarıdaki parametreler, gizli erişim şifresi ve yapılan isteğe özgü birtakım bilgiler kullanılarak oluşturulmuş signature.
Daha fazla bilgi için bkz. Signature Hesaplama Algoritması

Signature Hesaplama Algoritması

Signature, isteğin doğru kaynaktan geldiğini doğrulamak için kullanılan bir sağlama değeridir. Yapılan isteğe özel olduğu için her istekte yeniden hesaplanıp, istekle birlikte gönderilmelidir. Signature değerini hesaplamak için:

Signature her request'e özeldir!

  1. Aşağıdaki değerleri uç uca birleştir
    • İsteğin yapıldığı URL'in ham hali (hostname, protocol ve query string dahil)
    • Üye işyeri hesabının API erişim anahtarı (API Key)
    • Üye işyeri hesabının gizli erişim şifresi (Secret Key)
    • İsteğe özgü oluşturulmuş rastgele bir string
    • Eğer mevcut ise isteğin body'si
  2. Birleştirilen string'in SHA-256 hash'ini hesapla
  3. Hash'in Base64 ile şifrelenmiş halini hesapla

Örnekler



Parametreler

Ad Değer
URL https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1
Request Body
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T

Signature Hesaplama

  • Full URL: https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1
  • Query String:
  • API Key: key-1
  • Secret Key: FooBar123!
  • Random Key: Xa15Fp11T
  • Request Body:
  • Birleştirilmiş String: https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1key-1FooBar123!Xa15Fp11T
  • Signature: L/F2ZAOH/AGXZPIULNHDGOFZ+D5JS1097UP6RH11VSO=

İsteğe Eklenecek Header'lar

Ad Değer
x-api-key key-1
x-rnd-key rGciw1df
x-auth-version V1
x-signature L/F2ZAOH/AGXZPIULNHDGOFZ+D5JS1097UP6RH11VSO=





Parametreler

Ad Değer
URL https://api-gateway.oderopay.com.tr/onboarding/v1/buyers
Request Body {"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T

Signature Hesaplama

  • Full URL: https://api-gateway.oderopay.com.tr/onboarding/v1/buyers
  • Query String:
  • API Key: key-1
  • Secret Key: FooBar123!
  • Random Key: Xa15Fp11T
  • Request Body: {"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Birleştirilmiş String: https://api-gateway.oderopay.com.tr/onboarding/v1/buyerskey-1FooBar123!Xa15Fp11T{"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Signature: IRWQTISFBKCSM/NGZZ9XGN9PCTBXC0YSUJIBZMUZ9VS=

İsteğe Eklenecek Header'lar

Ad Değer
x-api-key key-1
x-rnd-key Xa15Fp11T
x-auth-version V1
x-signature IRWQTISFBKCSM/NGZZ9XGN9PCTBXC0YSUJIBZMUZ9VS=