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ıtlarodemehub.response, sabit kümelerodemehub.enumsmodü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çinclear=["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",
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
| Hata | Durum |
|---|---|
AuthenticationError | 401 |
ForbiddenError | 403 |
NotFoundError | 404 |
ValidationError | 422 |
RateLimitError | 429 |
UnexpectedResponseError | Diğer kodlar (500 dahil) ya da okunamayan yanıt; error.status. |
SignatureError | Yanıtın imzası tutmadı. |
TransportError | Gateway'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;teamyok) 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ıtlarPartnerTeamDetails,PartnerTeamList(pagination) veDeletedTeam; ç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ınClient'ını kurar. Bkz. İş Ortakları. - Yalnızca iş ortağı çalışma alanlarına açık uçlar (
Clientüzerinde; başka çalışma alanındaForbiddenError):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) vecreate_logo()(CreateLogo.from_bytes()). YanıtlarProviderList,PaymentProviderDetails,PaymentProviderList,DeletedPaymentProvider,WebhookEndpointDetails,WebhookEndpointList,DeletedWebhookEndpoint,TeamDetails,CheckoutDesignDetailsveLogoDetails. 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 isteklerindemax_installments;Order,SubscriptionvePaymentLinkyanıtlarındamax_installments(yoksaNone). GüncellemedeMaxInstallments()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(); isteklerRetrieveBanks,CreateBankAccount,RetrieveBankAccounts,UpdateBankAccount,DeleteBankAccount,RetrieveBankTransactions, yanıtlarBankList,BankAccountDetails,BankAccountList,DeletedBankAccount,BankTransactionList(Pagination,BankTransaction). Bankanın reddettiği kimlik bilgisi hata değildir:result.successfulFalse,bank_accountNone. Bkz. Banka Hareketleri. - Sorgularda sayfalama: altı sorgu isteği
pageveper_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ı varsapaginationtoplamı 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
.testdahil),Item.imagehttp ya da https, en çok 100 kalem, gönderim adresinde firma alanları422,NotFoundErroryalnızca token'lı güncelleme/silme/iade/iptalde. Kod değişmedi.
Kırıcı değişiklik:
RefundStatuskaldı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_addressileRegularPaymentveSecurePayment'ıncustomeralanı 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 eksiklerValidationError(422) alır.CreateSavedCard'dacustomervereferencezorunlu kalır,billing_addressverilmeyebilir. 403anlatımı:ForbiddenErroraçı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_saveaçı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_urlaçıklaması entegrasyonuhttps://sandbox.odemehub.comüzerinde kurar; canlıya çıkarkenbase_urlhttps://app.odemehub.comolur. Bkz. Ortamlar ve Adresler. PaymentCustomer: ödemenin ve kart saklamanın müşterisi. Yalnızcabilling_address(zorunlu) vereferencetaşı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,SecurePaymentveCreateSavedCardCustomerdeğilPaymentCustomeralır. Gateway ödemede ve kart saklamada gönderim adresini422ile reddeder;shipping_addresstaşıyabilenCustomerbu isteklerden çıktı. Ödeme kodundaCustomer(→PaymentCustomer(;billing_addressartık zorunludur.CreateOrderveCreateSubscriptionCustomeralmaya devam eder.
1.0.3'teki değişiklikler
- Müşteri kilidi ve müşteriye e-posta:
CreateOrder,UpdateOrder,CreateSubscriptionveUpdateSubscriptionlocks_customerveemails_customeralır.OrderveSubscriptionyanıtlarırequires_shipping,locks_customerveemails_customertaşır. Bkz.create-orderve E-postalar. - Kırıcı: ödeme linkinde
emails_payer→emails_customer.CreatePaymentLink,UpdatePaymentLinkvePaymentLinkyanıtında alanın adı değişti; gateway eskiemails_payeradını kabul etmez.
1.0.2'deki değişiklikler
Eklenenler:
- Link ödemeleri:
retrieve_link_payments()veRetrieveLinkPayments(token,LINKPAY{n}biçimindereferenceya dacreated_from/created_to). YanıtLinkPaymentList(paid()); herLinkPaymentpayment_link(token,reference), kalemler, tutarlar,discount,customer,transactionveis_paid()taşır. Yeni enum:LinkPaymentStatus(OPEN,PAID). Bkz.retrieve-link-payments. link_payment_token:PaymentTransaction,TransactionveWebhooklinkte alınan ödemedepayment_link_token'ın yanında link ödemesinin token'ını verir.- Ödeme linki alanları:
CreatePaymentLinkveUpdatePaymentLinkamount_type(AmountType),item_name,predefined_amounts,tax_rate,tax_mode(TaxMode),currency_type(CurrencyType),currenciesveemails_payer(1.0.3'teemails_customeroldu) alır;PaymentLinkyanıtı aynı alanları taşır. Güncellemeninclearlistesiitem_name,predefined_amounts,tax_ratevecurrenciesalanlarını da boşaltır. discount:Order,SubscriptionveLinkPaymentyanıtlarıDiscount(code,amount) taşır; kupon yoksaNone. 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_subscriptionvecreate_payment_linkaynıreferenceile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt güncellenmez,422dönmez. Yanıttaki token'ı saklayın, değişiklik içinupdate_*kullanın. Bkz. Aynı referansla tekrarlanancreate-*istekleri.CreatePaymentLink.itemsisteğe bağlıdır (yalnızcaFIXEDtipte gerekir). Alanlar adla verildiği için mevcut çağrılar etkilenmez.PaymentLink.subtotal,tax_amountveamountartıkstr | None: tutarı ödeyenin belirlediği linkteNonegelir (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 dafrom_body()kullanın. - Sonuçlanmamış ödeme yalnızca
update_orderveupdate_subscriptionçağrılarını engeller;create_*veupdate_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-Timestampile, 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_cardkaldırıldı. Yerlerinecreate_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 tekretrieve_*sorgusu eklendi. Kalemler (Item) adı ve fiyatıyla gönderilir. - Token: Tek kaydı adlandıran istek alanı her yerde
token'dır. - Müşteri:
Customerartıkreference,billing_addressveshipping_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 alanlarodemehub.enumsenum'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, isteklerdekichannel_tokenveChannelMessageyoktur. Referans alanlarıchannel_referenceyerinereferenceadını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlardachannel_tokenyoktur. Geri dönüşte tarayıcıchannel_referencedeğilreferencePOST eder. - Sorgular tek uçta. Her kaynakta tek sorgu metodu vardır:
retrieve_payments,retrieve_orders,retrieve_subscriptions,retrieve_payment_links,retrieve_saved_cards. İstektoken,reference,created_from/created_toalır ya da boş verilir; yanıt her zaman listedir, bulunamayan kayıtNotFoundErrordeğil boş listedir. GET isteği kalmadı. - Gönderim: sipariş ve abonelik
requiresShippingile ö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_rateisteğe bağlı; yenisave_as_product. - Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur.
referencevebilling_addressNoneolabilir. - Ödeme linki: son 50 deneme ve
transactions_countretrieve_payment_links()yanıtında herPaymentLinküzerindedir;PaymentLinkDetailsyalnızca linki taşır. - Kayıtlı kart: listede her kart kendi
customer'ını taşır;SavedCardList.customerkalktı. Listelenen ödemedesaved_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.