Ana içeriğe geç

Python SDK

Kurulum​

Python 3.10 ve üzeri gerekir. Yalnızca standart kütüphaneyi kullanır.

pip install odemehub

Bu sayfa 1.0.8 sürümünü anlatır. Önceki sürümlerden geçiş için: 1.0.8, 1.0.7, 1.0.6, 1.0.5, 1.0.4, 1.0.3, 1.0.2. 1.0.0 bugünkü gateway'le çalışmaz; geçiş için: 1.0.1'deki kırıcı değişiklikler.

İstemci​

import os

from odemehub import Client, Options

client = Client(Options(
base_url="https://sandbox.odemehub.com",
team=os.environ["ODEMEHUB_TEAM"], # Çalışma Alanı Kimliği
api_key=os.environ["ODEMEHUB_API_KEY"],
api_secret=os.environ["ODEMEHUB_API_SECRET"],
# timeout=60.0, # saniye
))

İstekler urllib ile gönderilir. Başka bir HTTP istemcisi için send(method, url, headers, body, timeout) metodu olan bir nesne Client(options, transport=...) ile verilebilir; her istek gövdeli bir POST'tur.

  • Her uç için uçla aynı adı taşıyan bir metot vardır: create-order → create_order(). Liste: SDK'lar.
  • İstekler odemehub.request, yanıtlar odemehub.response, sabit kümeler odemehub.enums modülündedir. İstek alanları yalnızca adla verilir; verilmeyen isteğe bağlı alan gövdeye yazılmaz. Update* isteklerinde bir alanı boşaltmak için clear=["description"] verilir.
  • Yanıtlar API JSON'unu birebir izler (payment.transaction.token, details.order.checkout_url). Sabit kümeli alanlar enum'dur; SDK'nın bilmediği bir değer metin olarak gelir.
  • Tek bir kaydı adlandıran istek alanı her zaman token'dır.

Müşteri ve kart​

from odemehub.request import Address, Card, PaymentCustomer

billing_address = Address(
firstname="Ahmet", lastname="Yılmaz",
email="[email protected]", phone="05551112233",
address="Kızılırmak Mah. Dumlupınar Blv. No:3",
district="Çankaya", province="Ankara", country="TR",
# company_title=..., tax_number=..., tax_office=...
)

customer = PaymentCustomer(reference="musteri-88", billing_address=billing_address)

card = Card(
holder_name="AHMET YILMAZ",
number="5400360000000003",
expiry_month="12",
expiry_year="2030",
security_code="000",
should_save=False,
)

Ödeme ve kart saklama istekleri PaymentCustomer alır; gönderim adresi yoktur. Fatura adresi zorunludur; Varsayılan Ödeyen açıksa billing_address'i ya da alanlarından bazılarını vermeyebilirsiniz, eksikler varsayılan ödeyenden tamamlanır. RegularPayment ve SecurePayment'ta customer da verilmeyebilir; CreateSavedCard'da customer ve reference yine zorunludur. Sipariş ve abonelik Customer alır; orada billing_address ve shipping_address isteğe bağlıdır.

Regular ödeme​

from odemehub.request import RegularPayment

payment = client.regular_payment(RegularPayment(
reference="SIP-10231",
amount="450.00",
installment_number=1,
ip=request.remote_addr,
customer=customer,
card=card,
))

if payment.result.successful:
payment.transaction.token # iade, iptal ve sorgu için
payment.transaction.payment_status # PaymentStatus.PAID

3D Secure ödeme​

from odemehub.request import RetrievePayments, SecurePayment

payment = client.secure_payment(SecurePayment(
reference="SIP-10231",
amount="450.00",
installment_number=1,
ip=request.remote_addr,
customer=customer,
callback_url="https://magazam.com/odeme/donus",
card=card,
))

if payment.redirect_url is not None:
return redirect(payment.redirect_url)

# callback_url işleyicisinde:
payments = client.retrieve_payments(RetrievePayments(token=request.form["transaction_token"])).payments
payments and payments[0].is_successful()

Sipariş, ödeme linki, abonelik, kayıtlı kart​

from odemehub.request import CreateOrder, Customer, Item, MaxInstallments

created = client.create_order(CreateOrder(
reference="SIP-10233",
success_url="https://magazam.com/tesekkurler",
items=[Item(name="Kahve makinesi", unit_amount="450.00", quantity=1, tax_rate="20")],
customer=Customer(reference="musteri-88", billing_address=billing_address),
requires_shipping=True, # ödeme sayfasında gönderim yöntemi seçilir, ücreti tutara eklenir
locks_customer=True, # müşteri bilgisi sorulmaz, gönderildiği gibi gösterilir
emails_customer=True, # ödeme tamamlanınca fatura adresindeki e-postaya yazılır
max_installments=MaxInstallments(individual=1, commercial=3), # bireysel kartta tek çekim, ticari kartta en çok 3 taksit
))

return redirect(created.order.checkout_url)

locks_customer=True eksiksiz fatura adresi ister; requires_shipping de açıksa gönderim adresi shipping_address'ten, verilmezse fatura adresinden alınır. Aynı üç alan UpdateOrder, CreateSubscription ve UpdateSubscription'da da vardır; Order ve Subscription yanıtları üçünü de taşır. Ödeme linkinde yalnızca emails_customer vardır ve e-posta, ödeyenin ödeme sayfasında verdiği adrese gider.

Diğer örnekler uç sayfalarındadır: create-order, create-payment-link, retrieve-link-payments, create-subscription, create-saved-card ve rehberler.

İade ve iptal​

from odemehub.request import CancelPayment, RefundPayment

refund = client.refund_payment(RefundPayment(token=transaction_token, amount="100.00"))
refund.refund.amount if refund.refund else None

client.cancel_payment(CancelPayment(token=transaction_token))

Hata yönetimi​

Gateway isteği reddederse hata fırlatılır; reddedilen ödeme, iade ya da kart saklama hata değildir (result.successful False).

from odemehub import NotFoundError, OdemehubError, RateLimitError, ValidationError

try:
payment = client.regular_payment(payment_request)
except ValidationError as error:
error.errors # {'transaction.amount': ['...']} (422)
except RateLimitError as error:
error.retry_after # 429; beklenecek saniye (Retry-After)
except NotFoundError:
... # 404
except OdemehubError as error:
print(error) # Türkçe
HataDurum
AuthenticationError401
ForbiddenError403
NotFoundError404
ValidationError422
RateLimitError429
UnexpectedResponseErrorDiğer kodlar (500 dahil) ya da okunamayan yanıt; error.status.
SignatureErrorYanıtın imzası tutmadı.
TransportErrorGateway'e ulaşılamadı; sonuç bilinmiyor.

Bkz. Hatalar.

1.0.8'deki değişiklikler​

Eklenenler:

  • İş ortağı istemcisi: PartnerClient (PartnerOptions: base_url, api_key, api_secret, timeout; team yok) iş ortağının anahtarıyla /api/partner/ uçlarını çağırır: create_team(), retrieve_teams() (sayfalı), update_team_modules(), delete_team(). Yanıtlar PartnerTeamDetails, PartnerTeamList (pagination) ve DeletedTeam; çalışma alanı PartnerTeam (slug, name, timezone, is_test, modules, gateway_url, api_key, api_secret, created_at). team_client(team) açılan çalışma alanının Client'ını kurar. Bkz. İş Ortakları.
  • Yalnızca iş ortağı çalışma alanlarına açık uçlar (Client üzerinde; başka çalışma alanında ForbiddenError): retrieve_providers(), create_payment_provider(), retrieve_payment_providers(), update_payment_provider(), delete_payment_provider(), create_webhook_endpoint(), retrieve_webhook_endpoints(), update_webhook_endpoint(), delete_webhook_endpoint(), update_team(), retrieve_checkout_design(), update_checkout_design() (clear=["logo", "terms_url"] kaldırır) ve create_logo() (CreateLogo.from_bytes()). Yanıtlar ProviderList, PaymentProviderDetails, PaymentProviderList, DeletedPaymentProvider, WebhookEndpointDetails, WebhookEndpointList, DeletedWebhookEndpoint, TeamDetails, CheckoutDesignDetails ve LogoDetails. Bkz. yalnızca iş ortağı çalışma alanlarına açık uçlar.

Kırıcı değişiklik yok.

1.0.7'deki değişiklikler​

Eklenenler:

  • Taksit sınırı: MaxInstallments (individual, commercial) ve sipariş, abonelik ve ödeme linki oluşturma/güncelleme isteklerinde max_installments; Order, Subscription ve PaymentLink yanıtlarında max_installments (yoksa None). Güncellemede MaxInstallments() sınırı kaldırır. Bkz. Taksit sınırı.

1.0.6'daki değişiklikler​

Eklenenler:

  • Banka hareketleri: retrieve_banks(), create_bank_account(), retrieve_bank_accounts(), update_bank_account(), delete_bank_account(), retrieve_bank_transactions(); istekler RetrieveBanks, CreateBankAccount, RetrieveBankAccounts, UpdateBankAccount, DeleteBankAccount, RetrieveBankTransactions, yanıtlar BankList, BankAccountDetails, BankAccountList, DeletedBankAccount, BankTransactionList (Pagination, BankTransaction). Bankanın reddettiği kimlik bilgisi hata değildir: result.successful False, bank_account None. Bkz. Banka Hareketleri.
  • Sorgularda sayfalama: altı sorgu isteği page ve per_page (en çok 250) alır; liste yanıtları pagination (Pagination, has_more()) taşır. Sayfalama. Gateway'de davranış değişikliği: sayfa istemeyen sorgu artık bütün kayıtları değil ilk 250'yi döner; daha fazlası varsa pagination toplamı gösterir, kalanını sayfa sayfa isteyin. SDK tarafında var olan kod değişmeden çalışır.

Değişenler:

  • Açıklama düzeltmeleri: dönüş adresleri (canlıda herkese açık https, sandbox'ta localhost ve .test dahil), Item.image http ya da https, en çok 100 kalem, gönderim adresinde firma alanları 422, NotFoundError yalnızca token'lı güncelleme/silme/iade/iptalde. Kod değişmedi.

Kırıcı değişiklik:

  • RefundStatus kaldırıldı; gateway iade durumu döndürmediği için hiçbir yanıtta kullanılmıyordu. Bu enum'u kullanan kod derlenmez; kullanımı silin.

1.0.5'teki değişiklikler​

Eklenenler:

  • Varsayılan Ödeyen: fatura adresi isteğe bağlı. PaymentCustomer.billing_address ile RegularPayment ve SecurePayment'ın customer alanı artık isteğe bağlıdır (varsayılanı None); verilmezse gövdeye yazılmaz. Varsayılan Ödeyen açıksa eksik ya da hiç verilmemiş fatura bilgisi varsayılan ödeyenden tamamlanır; kapalıyken sekiz kişi alanı yine zorunludur ve eksikler ValidationError (422) alır. CreateSavedCard'da customer ve reference zorunlu kalır, billing_address verilmeyebilir.
  • 403 anlatımı: ForbiddenError açıklaması ve README'deki hata tablosu iki nedeni anlatır: çalışma alanının ödenmemiş bakiyesi ya da ucun modülünün kapalı olması. Card.should_save açıklaması Kayıtlı Kartlar modülünü anar. Kod değişmedi; bkz. 403.

Kırıcı değişiklik yoktur; alanlar adla verildiği için 1.0.4 kodu değişmeden çalışır.

1.0.4'teki değişiklikler​

Eklenenler:

  • Sandbox'la başlayan kurulum: README ve Options.base_url açıklaması entegrasyonu https://sandbox.odemehub.com üzerinde kurar; canlıya çıkarken base_url https://app.odemehub.com olur. Bkz. Ortamlar ve Adresler.
  • PaymentCustomer: ödemenin ve kart saklamanın müşterisi. Yalnızca billing_address (zorunlu) ve reference taşır.
  • Webhook anlatımı: README menüyü (Ödeme Ayarları → Webhook), bir adrese birden çok olay bağlanmasını ve olaydan 30 saniye sonraki ilk gönderimi anlatır. Bkz. Webhook.

Kırıcı değişiklik:

  • RegularPayment, SecurePayment ve CreateSavedCard Customer değil PaymentCustomer alır. Gateway ödemede ve kart saklamada gönderim adresini 422 ile reddeder; shipping_address taşıyabilen Customer bu isteklerden çıktı. Ödeme kodunda Customer( → PaymentCustomer(; billing_address artık zorunludur. CreateOrder ve CreateSubscription Customer almaya devam eder.

1.0.3'teki değişiklikler​

  • Müşteri kilidi ve müşteriye e-posta: CreateOrder, UpdateOrder, CreateSubscription ve UpdateSubscription locks_customer ve emails_customer alır. Order ve Subscription yanıtları requires_shipping, locks_customer ve emails_customer taşır. Bkz. create-order ve E-postalar.
  • Kırıcı: ödeme linkinde emails_payer → emails_customer. CreatePaymentLink, UpdatePaymentLink ve PaymentLink yanıtında alanın adı değişti; gateway eski emails_payer adını kabul etmez.

1.0.2'deki değişiklikler​

Eklenenler:

  • Link ödemeleri: retrieve_link_payments() ve RetrieveLinkPayments (token, LINKPAY{n} biçiminde reference ya da created_from / created_to). Yanıt LinkPaymentList (paid()); her LinkPayment payment_link (token, reference), kalemler, tutarlar, discount, customer, transaction ve is_paid() taşır. Yeni enum: LinkPaymentStatus (OPEN, PAID). Bkz. retrieve-link-payments.
  • link_payment_token: PaymentTransaction, Transaction ve Webhook linkte alınan ödemede payment_link_token'ın yanında link ödemesinin token'ını verir.
  • Ödeme linki alanları: CreatePaymentLink ve UpdatePaymentLink amount_type (AmountType), item_name, predefined_amounts, tax_rate, tax_mode (TaxMode), currency_type (CurrencyType), currencies ve emails_payer (1.0.3'te emails_customer oldu) alır; PaymentLink yanıtı aynı alanları taşır. Güncellemenin clear listesi item_name, predefined_amounts, tax_rate ve currencies alanlarını da boşaltır.
  • discount: Order, Subscription ve LinkPayment yanıtları Discount (code, amount) taşır; kupon yoksa None. Webhook gövdesinde yoktur.

Küçük kırıcı değişiklikler:

  • create_* her çağrıda yeni kayıt açar. create_order, create_subscription ve create_payment_link aynı reference ile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt güncellenmez, 422 dönmez. Yanıttaki token'ı saklayın, değişiklik için update_* kullanın. Bkz. Aynı referansla tekrarlanan create-* istekleri.
  • CreatePaymentLink.items isteğe bağlıdır (yalnızca FIXED tipte gerekir). Alanlar adla verildiği için mevcut çağrılar etkilenmez.
  • PaymentLink.subtotal, tax_amount ve amount artık str | None: tutarı ödeyenin belirlediği linkte None gelir (eskiden '').
  • Yanıt modellerine zorunlu alanlar eklendi (PaymentLink, Order, Subscription, Transaction, Webhook). Bu sınıfları testlerde elle kuruyorsanız yeni alanları da verin ya da from_body() kullanın.
  • Sonuçlanmamış ödeme yalnızca update_order ve update_subscription çağrılarını engeller; create_* ve update_payment_link çağrılarını engellemez.

1.0.1'deki kırıcı değişiklikler​

1.0.1, SDK'yı geçidin bugünkü API'sine taşır ve 1.0.0 koduyla uyumlu değildir. 1.0.0'dan geçerken dikkat edilecekler:

  • İmza: İstekler ve yanıtlar X-Timestamp ile, zaman damgası, metot, yol ve gövde üzerinden imzalanır. 1.0.0 bugünkü gateway'le konuşamaz.
  • Uçlar: order_payment, subscription_payment, save_product, cancel_subscription, retrieve_transactions, save_card, saved_cards, default_saved_card kaldırıldı. Yerlerine create_order, create_subscription, update_subscription(status=SubscriptionStatus.CANCELLED), retrieve_payments, create_saved_card, retrieve_saved_cards, update_saved_card; ödeme linki, update_* uçları ve her kaynakta tek retrieve_* sorgusu eklendi. Kalemler (Item) adı ve fiyatıyla gönderilir.
  • Token: Tek kaydı adlandıran istek alanı her yerde token'dır.
  • Müşteri: Customer artık reference, billing_address ve shipping_address (Address) taşır; firma bilgisi fatura adresindedir.
  • Yanıtlar iç içe: payment.transaction.token, refund.refund.amount, details.order, details.subscription, details.payment_link. Sabit kümeli alanlar odemehub.enums enum'larıdır.
  • Hatalar: güncellenen, silinen, iade ya da iptal edilen kaydın token'ı bulunamazsa NotFoundError (404) atılır; eskiden bu durum 422 dönüyordu. Sorgular bulunamayan kayıtta boş liste döner. Yeni istisnalar: ForbiddenError (403), NotFoundError (404), RateLimitError (429, retry_after).
  • Kanal kalktı. Options.channel_token, isteklerdeki channel_token ve ChannelMessage yoktur. Referans alanları channel_reference yerine reference adını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlarda channel_token yoktur. Geri dönüşte tarayıcı channel_reference değil reference POST eder.
  • Sorgular tek uçta. Her kaynakta tek sorgu metodu vardır: retrieve_payments, retrieve_orders, retrieve_subscriptions, retrieve_payment_links, retrieve_saved_cards. İstek token, reference, created_from/created_to alır ya da boş verilir; yanıt her zaman listedir, bulunamayan kayıt NotFoundError değil boş listedir. GET isteği kalmadı.
  • Gönderim: sipariş ve abonelik requiresShipping ile ödeme sayfasında gönderim adresi ister; gönderim yöntemleri panelde tanımlanır, istekte gönderilmez. Yanıtta yalnızca ödeyenin seçtiği yöntem (shippingMethod: reference, title, amount, taxRate) gelir.
  • Kalemler: tax_rate isteğe bağlı; yeni save_as_product.
  • Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur. reference ve billing_address None olabilir.
  • Ödeme linki: son 50 deneme ve transactions_count retrieve_payment_links() yanıtında her PaymentLink üzerindedir; PaymentLinkDetails yalnızca linki taşır.
  • Kayıtlı kart: listede her kart kendi customer'ını taşır; SavedCardList.customer kalktı. Listelenen ödemede saved_card, kartın saklanması istendiyse saklanan kartı verir.

Webhook'lar​

Tek okuyucu vardır: webhook(method, path, body, timestamp, signature) imzayı (X-Timestamp + X-Signature) doğrular ve response.Webhook döner. Nesne yalnızca token taşır: order_token, payment_link_token, link_payment_token, subscription_token, transaction_token. Kararı bu token'larla çağırdığınız retrieve yanıtına göre verin. Yalnızca imzayı doğrulamak için verify_webhook() kullanılır.

Olaylar, adres tanımlama ve her dildeki örnek işleyici: Webhook.