Ana içeriğe geç

SDK'lar

SDKPaketGereksinimSayfa
PHPodemehub/php-sdk (Composer)PHP 8.2+, GuzzlePHP
Node.js@odemehub/node-sdk (npm)Node.js 18+Node.js
Pythonodemehub (pip)Python 3.10+Python
Javacom.odemehub:java-sdk:1.0.8 (Maven)Java 17+, JacksonJava

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 kuran teamClient / 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ıtta pagination). Gateway artık sayfa istemeyen sorguya bütün kayıtları değil ilk 250'yi döner. Kırıcı: RefundStatus kaldırıldı (hiçbir yanıtta kullanılmıyordu). Node.js'de UpdatePaymentLink.reference ve taxMode null alır.
  • 1.0.5: Varsayılan Ödeyen açıksa ödeme ve kart saklama istekleri fatura adresi eksik ya da hiç olmadan gider: PaymentCustomer'da billingAddress isteğe bağlıdır, ödemede customer hiç gönderilmeyebilir. Kart saklarken reference yine zorunludur; ayar kapalıyken eksikler 422 alır. 403 açı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.com kullanır, canlıda baseUrl https://app.odemehub.com olur (Ortamlar ve Adresler). PHP, Python ve Java'da ödeme ve kart saklama istekleri Customer yerine PaymentCustomer alır (yalnızca reference ve zorunlu billingAddress; 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) ve emailsCustomer (müşteriye e-posta); yanıtlarda requiresShipping, locksCustomer, emailsCustomer. Kırıcı: ödeme linkinde emailsPayer → emailsCustomer; gateway eski adı kabul etmez.
  • 1.0.2: retrieve-link-payments metodu ve link ödemesi modeli; işlem ve webhook nesnelerinde linkPaymentToken / link_payment_token; ödeme linkinde tutar tipi, seçimli tutarlar, KDV modu ve para birimi seçimi; sipariş, abonelik ve link ödemesinde discount. 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, apiSecret ile 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-Signature başlıklarıyla POST olarak 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 PartnerClient ayrıca kurulur: baseUrl, iş ortağının apiKey ve apiSecret'i; team yoktur. İ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 / JavaPython
secure-paymentsecurePaymentsecure_payment
regular-paymentregularPaymentregular_payment
refund-paymentrefundPaymentrefund_payment
cancel-paymentcancelPaymentcancel_payment
retrieve-paymentsretrievePaymentsretrieve_payments
retrieve-binretrieveBinretrieve_bin
create-ordercreateOrdercreate_order
retrieve-ordersretrieveOrdersretrieve_orders
update-order/{token}updateOrderupdate_order
create-payment-linkcreatePaymentLinkcreate_payment_link
retrieve-payment-linksretrievePaymentLinksretrieve_payment_links
update-payment-link/{token}updatePaymentLinkupdate_payment_link
retrieve-link-paymentsretrieveLinkPaymentsretrieve_link_payments
create-subscriptioncreateSubscriptioncreate_subscription
retrieve-subscriptionsretrieveSubscriptionsretrieve_subscriptions
update-subscription/{token}updateSubscriptionupdate_subscription
create-saved-cardcreateSavedCardcreate_saved_card
retrieve-saved-cardsretrieveSavedCardsretrieve_saved_cards
update-saved-card/{token}updateSavedCardupdate_saved_card
delete-saved-card/{token}deleteSavedCarddelete_saved_card
retrieve-banksretrieveBanksretrieve_banks
create-bank-accountcreateBankAccountcreate_bank_account
retrieve-bank-accountsretrieveBankAccountsretrieve_bank_accounts
update-bank-account/{token}updateBankAccountupdate_bank_account
delete-bank-account/{token}deleteBankAccountdelete_bank_account
retrieve-bank-transactionsretrieveBankTransactionsretrieve_bank_transactions
retrieve-providersretrieveProvidersretrieve_providers
create-payment-providercreatePaymentProvidercreate_payment_provider
retrieve-payment-providersretrievePaymentProvidersretrieve_payment_providers
update-payment-provider/{token}updatePaymentProviderupdate_payment_provider
delete-payment-provider/{token}deletePaymentProviderdelete_payment_provider
create-webhook-endpointcreateWebhookEndpointcreate_webhook_endpoint
retrieve-webhook-endpointsretrieveWebhookEndpointsretrieve_webhook_endpoints
update-webhook-endpoint/{token}updateWebhookEndpointupdate_webhook_endpoint
delete-webhook-endpoint/{token}deleteWebhookEndpointdelete_webhook_endpoint
update-teamupdateTeamupdate_team
retrieve-checkout-designretrieveCheckoutDesignretrieve_checkout_design
update-checkout-designupdateCheckoutDesignupdate_checkout_design
create-logocreateLogocreate_logo
partner/create-teamcreateTeam (PartnerClient)create_team (PartnerClient)
partner/retrieve-teamsretrieveTeams (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, JavaNode.js, PythonDurum
AuthenticationExceptionAuthenticationError401.
ForbiddenExceptionForbiddenError403; 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.
NotFoundExceptionNotFoundError404: 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.
ValidationExceptionValidationError422; errors alan → mesaj listesi.
RateLimitExceptionRateLimitError429; retryAfter / retry_after.
UnexpectedResponseExceptionUnexpectedResponseErrorDiğer durum kodları (500 dahil) ya da okunamayan yanıt; status HTTP kodu.
SignatureExceptionSignatureErrorYanıtın imzası tutmadı.
TransportExceptionTransportErrorGateway'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.