SDK'lar
| SDK | Paket | Gereksinim | Sayfa |
|---|---|---|---|
| PHP | odemehub/php-sdk (Composer) | PHP 8.2+, Guzzle | PHP |
| Node.js | @odemehub/node-sdk (npm) | Node.js 18+ | Node.js |
| Python | odemehub (pip) | Python 3.10+ | Python |
| Java | com.odemehub:java-sdk:1.0.8 (Maven) | Java 17+, Jackson | Java |
Bu sayfalar SDK'ların 1.0.8 sürümünü anlatır. 1.0.1'den beri SDK'lar gateway'in bugünkü imza yöntemini ve API'sini kullanır; kanallar yoktur, sorgular her kaynakta tek uçtadır ve müşteri yalnızca customer.reference ile adlandırılır. 1.0.0 bugünkü gateway'le çalışmaz; her SDK sayfasında "1.0.1'deki kırıcı değişiklikler" bölümü vardır.
Son sürümlerde değişenler:
- 1.0.8: İş Ortakları: iş ortağı anahtarıyla kurulan
PartnerClient(createTeam,retrieveTeams,updateTeamModules,deleteTeam; açılan çalışma alanının istemcisini kuranteamClient/team_client) ve çalışma alanı istemcisinde yalnızca iş ortağı çalışma alanlarına açık uçlar: ödeme hesapları, webhook adresleri,updateTeam, ödeme sayfası tasarımı ve logo. Kırıcı değişiklik yok. - 1.0.7: Sipariş, abonelik ve ödeme linkinde taksit sınırı: bireysel ve ticari kart için en fazla taksit (
maxInstallments/max_installments), yanıtlarda da okunur. Kırıcı değişiklik yok. - 1.0.6: Banka Hareketleri uçları ve sorgularda sayfalama (
page,perPage/per_page, yanıttapagination). Gateway artık sayfa istemeyen sorguya bütün kayıtları değil ilk 250'yi döner. Kırıcı:RefundStatuskaldırıldı (hiçbir yanıtta kullanılmıyordu). Node.js'deUpdatePaymentLink.referencevetaxModenullalır. - 1.0.5: Varsayılan Ödeyen açıksa ödeme ve kart saklama istekleri fatura adresi eksik ya da hiç olmadan gider:
PaymentCustomer'dabillingAddressisteğe bağlıdır, ödemedecustomerhiç gönderilmeyebilir. Kart saklarkenreferenceyine zorunludur; ayar kapalıyken eksikler422alır.403açıklamaları plan yerine modülleri anlatır: ödenmemiş bakiye ya da ucun modülü kapalı (403). 1.0.4 kodu değişmeden çalışır. - 1.0.4: Kurulum sandbox'la başlar: örnekler
https://sandbox.odemehub.comkullanır, canlıdabaseUrlhttps://app.odemehub.comolur (Ortamlar ve Adresler). PHP, Python ve Java'da ödeme ve kart saklama istekleriCustomeryerinePaymentCustomeralır (yalnızcareferenceve zorunlubillingAddress; gönderim adresi yok); Node.js'de bu tip zaten vardı. README'lerde webhook anlatımı güncellendi: menü Ödeme Ayarları → Webhook, bir adrese birden çok olay, ilk gönderim 30 saniye sonra. - 1.0.3: Sipariş ve abonelikte
locksCustomer(müşteri bilgisi ödeme sayfasında sorulmaz) veemailsCustomer(müşteriye e-posta); yanıtlardarequiresShipping,locksCustomer,emailsCustomer. Kırıcı: ödeme linkindeemailsPayer→emailsCustomer; gateway eski adı kabul etmez. - 1.0.2:
retrieve-link-paymentsmetodu ve link ödemesi modeli; işlem ve webhook nesnelerindelinkPaymentToken/link_payment_token; ödeme linkinde tutar tipi, seçimli tutarlar, KDV modu ve para birimi seçimi; sipariş, abonelik ve link ödemesindediscount.create-*metotları her çağrıda yeni kayıt açar.
Ayrıntılar her SDK sayfasının "değişiklikler" bölümlerindedir.
Ortak davranış
- İstemci
baseUrl,team,apiKey,apiSecretile bir kez kurulur. İstek adresi{baseUrl}/api/{team}/gateway/{uç}olarak oluşturulur. - Her istek JSON'a çevrilir, gizli anahtarla imzalanır ve
X-Api-Key,X-Timestamp,X-SignaturebaşlıklarıylaPOSTolarak gönderilir. Alanı olmayan istek{}gövdesiyle gider. - İsteğe bağlı alanlar verilmezse gövdeye yazılmaz. SDK'lar alanları kendileri denetlemez; kuralları gateway uygular.
- Yanıtın imzası doğrulanır ve yanıt, API JSON'unu birebir izleyen tipli bir nesneye çevrilir. Gateway'in reddettiği istekler istisna olarak atılır.
- İş ortağı uçları için
PartnerClientayrıca kurulur:baseUrl, iş ortağınınapiKeyveapiSecret'i;teamyoktur. İstek adresi{baseUrl}/api/partner/{uç}, imza ve yanıt doğrulaması aynıdır. Bkz. İş ortağı anahtarı. - Varsayılan zaman aşımı 60 saniyedir.
Metotlar
| Uç | PHP / Node.js / Java | Python |
|---|---|---|
secure-payment | securePayment | secure_payment |
regular-payment | regularPayment | regular_payment |
refund-payment | refundPayment | refund_payment |
cancel-payment | cancelPayment | cancel_payment |
retrieve-payments | retrievePayments | retrieve_payments |
retrieve-bin | retrieveBin | retrieve_bin |
create-order | createOrder | create_order |
retrieve-orders | retrieveOrders | retrieve_orders |
update-order/{token} | updateOrder | update_order |
create-payment-link | createPaymentLink | create_payment_link |
retrieve-payment-links | retrievePaymentLinks | retrieve_payment_links |
update-payment-link/{token} | updatePaymentLink | update_payment_link |
retrieve-link-payments | retrieveLinkPayments | retrieve_link_payments |
create-subscription | createSubscription | create_subscription |
retrieve-subscriptions | retrieveSubscriptions | retrieve_subscriptions |
update-subscription/{token} | updateSubscription | update_subscription |
create-saved-card | createSavedCard | create_saved_card |
retrieve-saved-cards | retrieveSavedCards | retrieve_saved_cards |
update-saved-card/{token} | updateSavedCard | update_saved_card |
delete-saved-card/{token} | deleteSavedCard | delete_saved_card |
retrieve-banks | retrieveBanks | retrieve_banks |
create-bank-account | createBankAccount | create_bank_account |
retrieve-bank-accounts | retrieveBankAccounts | retrieve_bank_accounts |
update-bank-account/{token} | updateBankAccount | update_bank_account |
delete-bank-account/{token} | deleteBankAccount | delete_bank_account |
retrieve-bank-transactions | retrieveBankTransactions | retrieve_bank_transactions |
retrieve-providers | retrieveProviders | retrieve_providers |
create-payment-provider | createPaymentProvider | create_payment_provider |
retrieve-payment-providers | retrievePaymentProviders | retrieve_payment_providers |
update-payment-provider/{token} | updatePaymentProvider | update_payment_provider |
delete-payment-provider/{token} | deletePaymentProvider | delete_payment_provider |
create-webhook-endpoint | createWebhookEndpoint | create_webhook_endpoint |
retrieve-webhook-endpoints | retrieveWebhookEndpoints | retrieve_webhook_endpoints |
update-webhook-endpoint/{token} | updateWebhookEndpoint | update_webhook_endpoint |
delete-webhook-endpoint/{token} | deleteWebhookEndpoint | delete_webhook_endpoint |
update-team | updateTeam | update_team |
retrieve-checkout-design | retrieveCheckoutDesign | retrieve_checkout_design |
update-checkout-design | updateCheckoutDesign | update_checkout_design |
create-logo | createLogo | create_logo |
partner/create-team | createTeam (PartnerClient) | create_team (PartnerClient) |
partner/retrieve-teams | retrieveTeams (PartnerClient) | retrieve_teams (PartnerClient) |
partner/update-team-modules/{slug} | updateTeamModules (PartnerClient) | update_team_modules (PartnerClient) |
partner/delete-team/{slug} | deleteTeam (PartnerClient) | delete_team (PartnerClient) |
İstek sınıfları da uçla aynı adı taşır (CreateOrder, RetrievePayments …); Node.js'de istekler düz nesnedir. Sorgu istekleri token, referans ya da tarih aralığıyla kurulur: PHP ve Java'da byToken, byReference, between, latest; Python'da token=, reference=, created_from=/created_to=; Node.js'de token, reference (kartlarda customerReference), createdFrom/createdTo. Yanıt her zaman listedir. Sorgulara sayfa da verilebilir (Sayfalama): PHP'de withPage($page, $perPage), Java'da .page(n) / .perPage(n), Node.js'de page / perPage, Python'da page= / per_page=. Gateway her sorguyu sayfalı yanıtlar; sayfa verilmezse ilk 250 kayıt gelir. Sayfa bilgisi yanıtın pagination alanındadır (hasMorePages(), Python'da has_more()); SDK'larda bu alan, gateway göndermezse null olabilecek biçimde okunur. Banka hareketi sorguları bu kalıba uymaz: hesaplar token listesiyle, hareketler hesap token'ları, tarih aralığı ve sayfayla sorulur. Ödeme hesabı ve webhook adresi sorguları sayfasızdır ve token listesiyle sorulur (Java'da all() / byTokens(...)); iş ortağının retrieveTeams'i slug listesiyle ya da sayfayla sorulur (İş Ortakları). Webhook okuma metotları her SDK sayfasının Webhook'lar bölümündedir.
İstisnalar
| PHP, Java | Node.js, Python | Durum |
|---|---|---|
AuthenticationException | AuthenticationError | 401. |
ForbiddenException | ForbiddenError | 403; iş ortağı çalışma alanı olmayan bir çalışma alanında yalnızca iş ortağı çalışma alanlarına açık uçlar da 403 alır. |
NotFoundException | NotFoundError | 404: güncellenen, silinen, iade ya da iptal edilen kaydın token'ı (iş ortağı uçlarında çalışma alanının slug'ı) bulunamadı. Sorgular 404 atmaz, boş liste döner. |
ValidationException | ValidationError | 422; errors alan → mesaj listesi. |
RateLimitException | RateLimitError | 429; retryAfter / retry_after. |
UnexpectedResponseException | UnexpectedResponseError | Diğer durum kodları (500 dahil) ya da okunamayan yanıt; status HTTP kodu. |
SignatureException | SignatureError | Yanıtın imzası tutmadı. |
TransportException | TransportError | Gateway'e ulaşılamadı. |
Temel sınıf: OdemehubException (PHP, Java) / OdemehubError (Node.js, Python). Sağlayıcının reddettiği ödeme istisna değildir; result.successful false döner. Ayrıntılar: Hatalar.
İmza yardımcısı
Her SDK bir Signature sınıfı içerir; gizli anahtarla kurulur ve metot, yol, gövde ve zaman damgasıyla imza üretir ve doğrular (PHP, Python, Java: sign / verify; Node.js: signMessage / verifyMessage). verify 5 dakikadan eski zaman damgasını geçersiz sayar. Bkz. Kimlik Doğrulama ve İmza.