Download the PHP package odemehub/php-sdk without Composer

ödemehub PHP SDK

ödemehub ödeme geçidini kendi uygulamanızdan kullanmak için PHP istemcisi. Kart çekmek, 3D ödeme başlatmak, sipariş, abonelik ve ödeme linki açmak, kart saklamak, iade ve iptal yapmak, taksit sormak, banka hesaplarının hareketlerini okumak: hepsi burada.

İstemci her isteği gizli anahtarınızla imzalar, gelen her yanıtın imzasını doğrular. Siz imza, başlık ya da JSON ayrıntılarıyla uğraşmazsınız. Her uç nokta için bir metot vardır ve adı uç noktanın adıdır: create-order için createOrder(), retrieve-saved-cards için retrieveSavedCards().

Uç noktaların, alanların ve akışların ayrıntılı anlatımı geliştirici dokümantasyonundadır: dev.odemehub.com.

Kurulum

PHP 8.2 ve üzeri gerekir.

Yapılandırma

Üç bilgi gerekir. Hepsi paneldeki Entegrasyon sayfasındadır: Çalışma Alanı Kimliğiniz, API anahtarı ve gizli anahtar.

Entegrasyonu sandbox'ta (https://sandbox.odemehub.com) geliştirin; sandbox'ta hesap açın ve bilgileri oradaki panelden alın. Canlıya çıkarken app.odemehub.com üzerinde açtığınız hesabın bilgileriyle baseUrl'i https://app.odemehub.com yapın.

Gizli anahtar hiçbir zaman tel üzerinden gitmez; yalnızca imza üretmekte ve doğrulamakta kullanılır. Anahtarları kodun içine yazmayın.

Geçit hiçbir yerde veritabanı numarası kullanmaz: ödeme hesabı, işlem, sipariş, abonelik, link, link ödemesi, kayıtlı kart, banka hesabı ve banka hareketi her zaman UUID token'ıyla anılır.

reference sizin etiketinizdir, tekil olması gerekmez. create-* çağrıları (createOrder, createSubscription, createPaymentLink) her seferinde yeni bir kayıt ve yeni bir token açar; aynı referansı ikinci kez göndermek eski kaydı değiştirmez, hata da döndürmez. Böylece 3D'de vazgeçen ödeyeni aynı referansla yeniden ödemeye gönderebilirsiniz. Her create yanıtındaki token'ı saklayın: kaydı sonradan bu token'la güncellersiniz ve sorgularsınız. Referansla sorgu (byReference()) o referanstaki bütün kayıtları döner.

İmza

Her istek üç başlıkla gider: X-Api-Key, X-Timestamp (Unix saniye) ve X-Signature. İmza, "{timestamp}\n{METHOD}\n{path}\n{body}" metni üzerinden gizli anahtarla alınan HMAC-SHA256'nın küçük harfli hex halidir. path adresin sorgu dizesiz yolu (/api/1000000001/gateway/regular-payment), body gönderilen JSON'ın kendisidir. Bütün uç noktalar POST'tur. Zaman damgası sunucu saatinden 5 dakikadan uzak olamaz. Geçit her yanıtı ve her webhook'u aynı yöntemle imzalar; istemci yanıtı isteğin metodu ve yoluyla, yanıtın kendi X-Timestamp değeriyle doğrular. Test vektörü Gurmehub\Odemehub\Signature sınıfının açıklamasındadır.

Karttan doğrudan çekim

Müşteri hiçbir yere gitmez. Başarılı yanıt, paranın alındığı anlamına gelir.

Reddedilen ödeme de bir sonuçtur: result->successful false, result->message neden. Yalnızca geçit isteğin kendisini reddederse (hatalı alan, yetki, hız sınırı) istisna fırlatılır.

Kayıtlı kartla ödemede card yerine savedCardToken verilir; ödeme kartın saklandığı hesaptan geçer, paymentProviderToken gönderilmez. Kart hangi müşteri referansıyla saklandıysa ödeme de aynı referansı taşımalıdır.

Ödeme ve kart saklama müşteriyi PaymentCustomer ile alır: yalnızca reference ve billingAddress. Gönderim adresi sipariş ve aboneliğe aittir; onlar Customer alır.

Varsayılan Ödeyen. Panelde Ödeme Ayarları → Varsayılan Ödeyen açıksa billingAddress eksik alanlarla verilebilir ya da hiç verilmeyebilir; gönderilmeyen alanlar ödeme sağlayıcısına varsayılan ödeyenin bilgisiyle gider, müşteri kaydına yazılmaz. Ödemede new PaymentCustomer() (adres de referans da yok) müşteriyi istekten tamamen çıkarır; kart saklamada reference yine zorunludur. Ayar kapalıyken sekiz kişi alanı zorunludur. SDK bunu denetlemez; eksik alanı geçit 422 ile bildirir.

Müşteriler. customer.reference gönderdiğiniz ödeme başarılı olunca geçit müşteriyi o referansla çalışma alanınızın müşteri listesine yazar ya da günceller; başarısız ödeme müşteriye dokunmaz. Referans göndermezseniz ödeme yine alınır ama müşteri kaydedilmez ve kart saklanamaz. Saklanan kart müşteriye bağlanır; müşterinin son ödeme yaptığı kart varsayılan kartı olur.

Tutarlar nokta ayraçlı ve en çok iki ondalıklı dizedir: '100', '100.1', '100.10'. Para birimi Enum\Currency ile verilir, boş bırakılırsa TRY'dir. Taksit yalnızca TRY'de 1'den büyük olabilir. Aynı anda satılan tutar ile çekilen tutar farklıysa (vade farkı) baseAmount verilir.

3D ödeme

Siz ödemeyi başlatırsınız, müşteri bankasına gider, banka müşteriyi sizin adresinize geri yollar.

Başarılı yanıt ödeme alındı demek değildir; müşterinin gideceği adres hazır demektir. Adres 15 dakika geçerlidir ve bir kez açılır; süresinde açılmayan ödeme expired olur.

callbackUrl, successUrl ve cancelUrl canlıda internetten erişilebilen bir https adresi olmalıdır; sandbox'ta localhost ve .test dahil her http/https adresi kabul edilir, yani dönüş adresi olarak kendi makinenizi kullanabilirsiniz.

Banka işini bitirince müşterinin tarayıcısı callbackUrl adresinize şu alanları POST eder: transaction_token, reference, successful (1/0). Bu POST imzasızdır ve müşterinin tarayıcısından gelir; yalnızca ipucudur. Sonucu kendi imzalı bağlantınızdan sorun:

Geçidin ödeme yanıtları (securePayment, regularPayment, refundPayment, cancelPayment) ödemeyi transaction altında tam verir: status, paymentStatus, securityType, amount, baseAmount, currency, installmentNumber, isTest, createdAt, ve ödeme bir siparişte, linkte ya da abonelikte alındıysa orderToken / paymentLinkToken / subscriptionToken. Linkte alınan ödemede paymentLinkToken ile birlikte ödeyenin link ödemesini adlandıran linkPaymentToken da dolu gelir.

Müşteri hiç dönmezse panelde tanımladığınız webhook adresi yine de haber alır (transaction.successful, transaction.failed, transaction.expired). Aşağıya bakın.

Sipariş

Kart sizde sorulmaz. Siparişi açarsınız, geçit kendi ödeme sayfasının adresini döner, müşteri orada öder. Tutar gönderilmez: geçit kalemleri ve seçilen gönderim yöntemini toplar. Birim tutarlar KDV dahildir.

Kupon. API'de kupon alanı yoktur; ödeyen kodu ödeme sayfasında girer. Kupon kullanılan siparişte $order->discount (code, amount) dolu gelir, kullanılmadıysa null'dır. Siparişin subtotal, taxAmount ve amount değerleri indirim düşülmüş tutarlardır; kupon gönderim ücretinden düşülmez.

Müşteri kilidi. locksCustomer: true gönderilirse ödeme sayfası müşteri bilgisi sormaz; gönderdiğiniz müşteriyi değiştirilemez şekilde gösterir ve ödemeyi onunla alır. Bu durumda fatura adresi eksiksiz olmalıdır; requiresShipping: true ise gönderim adresi de (gönderilmezse fatura adresi kullanılır). Gönderim adresi (shippingAddress) yalnızca sekiz kişi alanını alır; şirket unvanı, vergi numarası ya da vergi dairesi verilirse geçit 422 döner. Eksik alan varsa geçit 422 ile reddeder. Yanıttaki requiresShipping, locksCustomer ve emailsCustomer kaydın bu ayarlarını verir.

Taksit sınırı. maxInstallments ödeme sayfasında sunulacak en yüksek taksit sayısını bireysel (individual) ve ticari (commercial) kart için ayrı ayrı sınırlar: her biri 1–12, 1 yalnızca tek çekim, null o kart tipinde sınır yok. Sipariş, abonelik ve ödeme linkinde (Create* / Update*) aynı şekilde gönderilir. Güncellemede gönderilen sınır öncekinin yerini alır, gönderilmezse değişmez; new MaxInstallments() (ikisi de null) sınırı kaldırır. Yanıttaki maxInstallments (Order, Subscription, PaymentLink) sınır yoksa null'dır.

saveAsProduct: true olan kalem referansıyla ürün listenize yazılır (referans zorunlu). Gönderim yöntemleri istekte gönderilmez: panelinizdeki Gönderim Yöntemleri listesinden ödeyenin adresine uyanlar sunulur, seçilen $order->order->shippingMethod olarak döner.

Ödendiğinde müşteri successUrl adresinize 3D dönüşüyle aynı alanlarla POST edilir; kesin sonucu retrieveOrders() verir; order.paid webhook'u geldiğinde de onu çağırın. $order->transaction->paymentStatus sonradan yapılan iadeyi gösterir.

Aynı referansla createOrder() yeniden çağrılırsa yeni bir sipariş ve yeni bir token açılır; önceki sipariş olduğu gibi kalır. Var olan siparişi değiştirmek için updateOrder() ile token'ını gönderin. Bir istekte en çok 100 kalem gönderilir (sipariş, abonelik ve link). Ödenmiş sipariş değişmez. Bekleyen ödeme varken güncellenemez: ödeme sayfasında son 15 dakika içinde başlamış bir ödeme varsa updateOrder() ve updateSubscription() çağrıları token alanında "bekleyen bir ödeme var, tamamlanmasını bekleyin" ile reddedilir. Link güncellemesi bundan etkilenmez.

Ödeme linki

Link kim açarsa onun ödeyebileceği bir sayfadır; kapatılana ya da son gününe kadar tekrar tekrar ödenir. Müşterisi yoktur. Her createPaymentLink() çağrısı yeni bir link ve yeni bir token açar; linki sonradan token'ıyla güncellersiniz.

Tutarı ödeyen seçer. amountType (Enum\AmountType) linkte ne ödeneceğini söyler: Fixed (varsayılan) kalemlerin toplamı; Custom ödeyenin yazdığı tutar; Predefined predefinedAmounts içinden biri (en çok 10); PredefinedAndCustom ikisinden biri. Fixed dışındaki tiplerde ödeme itemName adında tek kalem olarak alınır, items gönderilmez (gönderilirse yok sayılır). taxRate ödenen tutardaki vergi oranıdır; taxMode (Enum\TaxMode) Inclusive (varsayılan) ise vergi tutarın içinden ayrılır, Exclusive ise üstüne eklenir. currencyType: CurrencyType::Selectable ile ödeyen currencies içinden para birimini seçer; currency başlangıçta seçili olandır ve her zaman listede yer alır.

Hangi alanın hangi tipte zorunlu olduğunu geçit denetler; eksik alan ValidationException (422) ile döner. updatePaymentLink() yalnızca token'la, değiştirilecek bir alan olmadan çağrılırsa geçit 422 döner; updateBankAccount() için de aynısı geçerlidir. Güncellemede clear listesi description, expires_at, payment_provider_token, item_name, predefined_amounts, tax_rate ve currencies alanlarını boşaltabilir. Fixed tipe dönen ya da Fixed kalan link kalemsiz kalamaz.

Link ödemeleri. Linkte yapılan her ödeme bir link ödemesidir (LINKPAY1, LINKPAY2…); ödeyen açar, siz yalnızca sorgularsınız:

Panelden açtığınız linkler de aynı uçlarla, token'ı ya da referansıyla bulunur. Linkle ödeyen kişi müşteri listenize yazılmaz ve kartı saklanmaz.

Abonelik

İlk yenileme ödeme sayfasında ödenir ve kart orada müşteriye saklanır; sonrakiler müşterinin varsayılan kartından çekilir. Müşteri referansı zorunludur. Hesap kart saklamalı ve 3D ödeme almalıdır.

İptalde para iade edilmez; ödenmiş dönem sonuna kadar sürer, sonra abonelik biter (subscription.ended). Ödenmiş dönem yoksa hemen cancelled olur.

Kupon yalnızca ilk ödemede, ödeme sayfasında girilir. $current->discount (code, amount) o kuponu verir, yoksa null'dır. Aboneliğin kendi subtotal / taxAmount / amount değerleri indirimsizdir; ilk dönemde gerçekten çekilen tutar renewal->amount'tadır.

locksCustomer siparişteki gibi çalışır. emailsCustomer açıkken dönem ödemesi alınamazsa ödeme sayfasının bağlantısı doğrudan müşteriye gider, size ayrıca e-posta gelmez.

İlk ödemeden sonra yalnızca iptal (status), ödeme sayısı (renewalLimit, ödenenden az olamaz), dönem (period) ve aynı kalemlerin birim fiyatı değişebilir; müşteri dahil başka bir alan gönderilirse geçit 422 ile reddeder.

Kayıtlı kartlar

Kart ödeme sırasında (shouldSave: true) ya da ödemesiz saklanır; ikisinde de customer.reference zorunludur. Kart o müşteriye bağlanır ve müşteri referansıyla bulunur; kart yanıtlarındaki customer yalnızca reference taşır. Ödemesiz saklamada müşteri, sağlayıcı kartı kabul edince gönderdiğiniz bilgilerle listenize yazılır.

Kayıtlı kart yanıtlarında kartın yalnızca ilk haneleri ve son dördü vardır. Request\Card nesnesi var_dump ve benzeri çıktılarda numarayı ve CVV'yi ***** olarak gösterir.

İade ve iptal

Ödemenin token'ı yeter. İade, sağlayıcının kapattığı ödemeden kısmen ya da tamamen; iptal, henüz kapatılmamış ödemenin tamamı.

Kart sorgusu ve taksitler

Kartın ilk 6–8 hanesiyle bankası, tipi ve tutara göre taksit seçenekleri. Hiçbir şey çekilmez.

Banka hareketleri

Banka hesabınızı bankanın verdiği API kimlik bilgileriyle eklersiniz; geçit hesabın hareketlerini saatte bir bankadan çekip saklar, siz hesabın token'ıyla sorarsınız. Uçlar Banka Hareketleri modülünü ister. Hangi bankanın eklenebildiğini ve hangi kimlik bilgilerini istediğini retrieveBanks() söyler; bugün yalnızca Enpara vardır.

Geçit hesabı eklemeden ve yeni kimlik bilgilerini kaydetmeden önce bankaya sorar. Bankanın reddi istisna değildir: result->successful false, bankAccount null döner ve hiçbir şey değişmez. Hesabın bankası ve IBAN'ı değişmez; aynı IBAN çalışma alanına bir kez eklenir. Kimlik bilgileri hiçbir yanıtta dönmez. Hesap silinince ondan okunan bütün hareketler de silinir.

Hareketler bankadan değil geçidin sakladığı kayıttan okunur; veri en çok bir saat geridedir. bankAccount->syncedAt son okumayı, lastError son okumanın neden başarısız olduğunu verir. Hesap eklenince son 7 günün hareketleri çekilir. Gün aralığı çalışma alanının saat dilimindedir, bankanın tarihine (booked_at) göre süzülür ve iki uç dahil en çok 7 gündür. Birden çok hesap verilirse hareketler bankanın tarihine göre iç içe, eskiden yeniye sıralanır. Banka hareketleri için webhook yoktur.

İş ortakları

İş ortağıysanız ödemehub'ı kendi uygulamanızın arkasında kullanır, müşterileriniz için çalışma alanlarını API'den açarsınız. İki anahtar vardır: iş ortağı anahtarı (panelde Ayarlar → İş Ortaklığı) yalnızca çalışma alanı açar, listeler, modüllerini değiştirir ve siler; çalışma alanının içindeki her iş o çalışma alanının kendi anahtarıyla, sıradan Client üzerinden yapılır. İmza ve hatalar ikisinde de aynıdır; iş ortağı yanıtları iş ortağının gizli anahtarıyla imzalanır.

Modüller: api, orders, subscription, payment_links, saved_cards, bank_transactions. Yanıtta custom_domain ve shopify_pos da görünebilir; onları yalnızca ödemehub açar, istekte gönderilirse 422 döner. Sandbox'ta bütün modüller açıktır: createTeam modülleri yok sayar, updateTeamModules 403 döner. Başka bir iş ortağının ya da var olmayan bir çalışma alanının slug'ı 404 döner. İş ortağı uçlarında sınır iş ortağı başına dakikada 60 istektir.

Çalışma alanı istemcisindeki şu uçlar yalnızca iş ortağının açtığı çalışma alanlarına açıktır; başka bir çalışma alanında ForbiddenException (403) döner:

• Ödeme hesapları: retrieveProviders(), createPaymentProvider(), retrievePaymentProviders(), updatePaymentProvider() (isDefault: true hesabı varsayılan yapar), deletePaymentProvider(). Ayarlar hiçbir yanıtta dönmez; sağlayıcıya bağlantı denenmez. Her ayar iki kez sorulur: canlı için anahtarın kendisi, test için test_ önekli hali.
• Webhook adresleri: createWebhookEndpoint(), retrieveWebhookEndpoints(), updateWebhookEndpoint(), deleteWebhookEndpoint(). Olaylar Enum\WebhookEvent ya da metin olarak verilir; yanıtta metindir.
• Çalışma alanı ve ödeme sayfası: updateTeam() (ad, saat dilimi), retrieveCheckoutDesign(), updateCheckoutDesign() (yalnızca verilen alanlar yazılır; clear: ['logo', 'terms_url'] bunları boşaltır), createLogo() (JPG, PNG ya da WEBP, en çok 2 MB ve 3000×3000 piksel; dönen url tasarımda logo olarak verilir).

Sorgulama

Her kaynak tek bir retrieve-* ucuyla sorulur ve yanıt her zaman bir listedir (eskiden yeniye); eşleşen yoksa boş liste döner. Kayıt üç yoldan biriyle adlandırılır: token'ı, sizdeki referansı ya da açıldığı günler. Gün aralığı en çok 7 gündür ve çalışma alanının saat dilimindedir; hiçbiri verilmezse son 7 gün.

Aynısı retrieveOrders (RetrieveOrders), retrieveSubscriptions (RetrieveSubscriptions), retrievePaymentLinks (RetrievePaymentLinks), retrieveLinkPayments (RetrieveLinkPayments; referans link ödemesinin LINKPAY{n} numarasıdır) ve retrieveSavedCards (RetrieveSavedCards; referans müşterinin referansıdır) için de geçerlidir. Referans tekil olmadığından byReference() o referanstaki bütün kayıtları döner.

Sayfalama. Bütün sorgu yanıtları sayfalıdır ve her zaman pagination (page, perPage, total, lastPage, hasMorePages()) taşır. Her sorgu isteği page ve perPage (en çok 250) alır; fabrika metotlarıyla kurulan isteğe withPage() eklenir. page verilip perPage verilmezse sayfa 50 kayıttır; ikisi de verilmezse ilk sayfa 250 kayıtla döner. Yoğun bir çalışma alanında 7 günde binlerce kayıt olabilir; pagination->total 250'yi aşıyorsa sayfa sayfa dolaşın. Sıralama değişmez.

Banka hesapları ve hareketleri bu kalıbın dışındadır: retrieveBankAccounts() yalnızca token listesi alır (boş: bütün hesaplar) ve sayfalı değildir; retrieveBankTransactions() hesap token'larıyla ve gün aralığıyla sorulur, sayfalaması yukarıdakiyle aynıdır.

Webhook

Sipariş ödendiğinde, link ödemesi alındığında, abonelik durum değiştirdiğinde, API ödemesi bittiğinde ve bir ödeme iade ya da iptal edildiğinde geçit imzalı JSON POST eder. Adresler kodda verilmez; panelde Ödeme Ayarları → Webhook sayfasında tanımlanır. Bir adres birden çok olayı dinleyebilir; Tüm olaylar seçilirse her olay o adrese gelir. Aynı olay birden çok adreste seçilirse bildirim her adrese ayrı gider.

Olaylar (Enum\WebhookEvent):

Sipariş, link ya da abonelikte alınan ödeme için transaction.* gelmez; o kaynağın kendi olayı gelir.

Webhook nihai sonuç değildir. Gövde yalnızca kaynağın token'ını (para hareketi varsa yanında ödemenin token'ını; payment_link.* olaylarında ayrıca link ödemesinin token'ını) taşır; discount gibi ayrıntılar gövdede yoktur. Kararı, token ile geçide sorduğunuz yanıta göre verin ve yanıtı kendi kaydınızla (referans, tutar, durum) karşılaştırın:

Sipariş, link ve abonelikte para hareketi olan olaylarda transactionToken da gelir; retrievePayments() yanıtındaki orderToken / paymentLinkToken / linkPaymentToken / subscriptionToken ödemenin gerçekten o kaynağa ait olduğunu gösterir.

Yalnızca doğrulamak için $client->verifyWebhook(...) bool döner. Adres https ve herkese açık olmalıdır.

İlk gönderim olaydan 30 saniye sonra yapılır. Geçit 2xx yanıt alana kadar 60 sn, 5 dk, 15 dk ve 30 dk arayla toplam 5 kez dener; yönlendirmeleri izlemez. Adres panelden kapatılır ya da silinirse otomatik gönderimler durur. Denemeleri biten bildirim panelde ilgili kaydın sayfasından elle yeniden gönderilebilir; elle gönderim beklemeden, aynı id ve gövdeyle, bildirim kaydındaki adrese gider.

Hatalar

Hepsi Gurmehub\Odemehub\Exception\OdemehubException türündendir.

Reddedilen ödeme, iade, kart saklama ya da bankanın reddettiği banka hesabı istisna değildir; result->successful false ve result->message dolu döner.

İstek sınırları

Sınırlar çalışma alanı başına ve dakikalıktır:

Aşıldığında 429 ve RateLimitException döner; retryAfter kadar bekleyip aynı isteği yeniden gönderin.

Değişiklikler

1.0.8

Eklenenler:

• İş ortağı istemcisi: PartnerClient (PartnerOptions: baseUrl, apiKey, apiSecret; team yok) iş ortağının anahtarıyla /api/partner/ uçlarını çağırır: createTeam() (create-team), retrieveTeams() (retrieve-teams, sayfalı), updateTeamModules() (update-team-modules/{slug}) ve deleteTeam() (delete-team/{slug}). Yanıtlar PartnerTeamDetails, PartnerTeamList (Pagination) ve DeletedTeam; çalışma alanı PartnerTeam (slug, name, timezone, isTest, modules, gatewayUrl, apiKey, apiSecret, createdAt). teamClient($team) o çalışma alanının Client'ını kurar.
• Yalnızca iş ortağı çalışma alanlarına açık uçlar (Client üzerinde; başka çalışma alanında 403): retrieveProviders(), createPaymentProvider(), retrievePaymentProviders(), updatePaymentProvider(), deletePaymentProvider(), createWebhookEndpoint(), retrieveWebhookEndpoints(), updateWebhookEndpoint(), deleteWebhookEndpoint(), updateTeam(), retrieveCheckoutDesign(), updateCheckoutDesign() ve createLogo(). Yanıtlar ProviderList (Provider, ProviderField), PaymentProviderDetails, PaymentProviderList (PaymentProvider), DeletedPaymentProvider, WebhookEndpointDetails, WebhookEndpointList (WebhookEndpoint), DeletedWebhookEndpoint, TeamDetails (Team), CheckoutDesignDetails (CheckoutDesign) ve LogoDetails.

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

1.0.7

Eklenenler:

• Taksit sınırı: MaxInstallments (individual, commercial; istek için Request\MaxInstallments, yanıt için Response\MaxInstallments). CreateOrder, UpdateOrder, CreateSubscription, UpdateSubscription, CreatePaymentLink ve UpdatePaymentLink maxInstallments alır; Order, Subscription ve PaymentLink yanıtları maxInstallments taşır (yoksa null). Güncellemede new MaxInstallments() sınırı kaldırır.

1.0.6

Eklenenler:

• Banka hareketleri: retrieveBanks() (retrieve-banks), createBankAccount() (create-bank-account), retrieveBankAccounts() (retrieve-bank-accounts), updateBankAccount() (update-bank-account/{token}), deleteBankAccount() (delete-bank-account/{token}) ve retrieveBankTransactions() (retrieve-bank-transactions). Yanıtlar BankList (Bank, BankField), BankAccountDetails, BankAccountList, DeletedBankAccount ve BankTransactionList (Pagination, BankTransaction); hareketin currency'si Enum\Currency'dir. Bankanın reddettiği kimlik bilgisi istisna değil, result->successful false ve bankAccount null döner. Uçlar Banka Hareketleri modülünü ister; kapalıysa ForbiddenException (403).
• Sayfalı hareketler: RetrieveBankTransactions page ve perPage (en çok 250; page verilip perPage verilmezse 50, ikisi de verilmezse 250) alır; yanıt pagination (page, perPage, total, lastPage, hasMorePages()) taşır.
• Sorgularda sayfalama: RetrievePayments, RetrieveOrders, RetrieveSubscriptions, RetrievePaymentLinks, RetrieveLinkPayments ve RetrieveSavedCards isteğe bağlı page ve perPage (en çok 250; page verilip perPage verilmezse 50) alır; fabrika metotlarıyla kurulan isteğe withPage($page, $perPage) eklenir. PaymentList, OrderList, SubscriptionList, PaymentLinkList, LinkPaymentList ve SavedCardList pagination (Pagination) taşır; geçit her yanıtta gönderir. Var olan kod değişmeden derlenir ve çalışır, ancak geçidin davranışı değişti: sayfa istemeyen bir sorgu artık bütün kayıtları değil ilk 250 kaydı döner; daha fazlası olabilecek sorgularda pagination->total'a bakıp sayfa sayfa dolaşın.

Değişenler:

• Dönüş adresleri: callbackUrl, successUrl ve cancelUrl açıklamaları geçidin kuralını yazar: canlıda internetten erişilebilen https adresi, sandbox'ta localhost ve .test dahil her http/https adresi. Item::$image http ya da https olabilir. Kod değişmedi.
• 404 açıklaması: NotFoundException ve README hata tablosu 404'ün yalnızca token'la adlandırılan güncelleme, silme, iade ve iptal çağrılarında döndüğünü, sorguların bulunamayan kaydı boş liste olarak döndüğünü söyler.
• Belgelenen sınırlar: bir istekte en çok 100 kalem; updatePaymentLink() ve updateBankAccount() yalnızca token'la çağrılırsa 422.
• Gönderim adresi: Customer::$shippingAddress açıklaması ve README, gönderim adresinin yalnızca sekiz kişi alanını aldığını, şirket alanlarıyla 422 döndüğünü söyler.

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

• RefundStatus kaldırıldı; geçit iade durumu döndürmediği için hiçbir yanıtta kullanılmıyordu.

1.0.5

Eklenenler:

• Varsayılan Ödeyen: PaymentCustomer'da billingAddress artık isteğe bağlıdır (?Address, varsayılanı null) ve verilmezse gönderilmez. Çalışma alanında Varsayılan Ödeyen açıksa RegularPayment, SecurePayment ve CreateSavedCard fatura adresi eksik ya da hiç verilmeden gönderilebilir; eksik alanlar ödeme sağlayıcısına varsayılan ödeyenden gider. Ödemede new PaymentCustomer() customer'ı istekten tamamen çıkarır. Ayar kapalıyken sekiz kişi alanı yine zorunludur; denetimi geçit yapar (422). Var olan kod değişmeden çalışır.

Değişenler:

• 403 açıklaması: plan sistemi kalktı. ForbiddenException (403) artık ödenmemiş bakiye ya da ucun modülünün kapalı olduğu anlamına gelir (Çalışma alanınızda bu modül kapalı; açtırmak için bizimle iletişime geçin.); modülleri ödemehub açar. README'deki hata tablosu ile ForbiddenException ve Card::$shouldSave açıklamaları buna göre güncellendi; kod değişmedi.

1.0.4

Eklenenler:

• Sandbox'la başlayan kurulum: README ve Options açıklaması entegrasyonu https://sandbox.odemehub.com üzerinde geliştirip canlıya çıkarken baseUrl'i https://app.odemehub.com yapmayı anlatır.
• Request\PaymentCustomer: ödemenin ve kart saklamanın müşterisi; yalnızca billingAddress (zorunlu) ve reference taşır.
• Webhook anlatımı güncellendi: menü Ödeme Ayarları → Webhook, bir adres birden çok olay (ya da Tüm olaylar), ilk gönderim olaydan 30 saniye sonra, kapatılan ya da silinen adrese otomatik gönderim yapılmaz, elle yeniden gönderim bildirim kaydındaki adrese gider.
• Dokümantasyon bağlantısı: README ve composer.json geliştirici dokümantasyonunu (dev.odemehub.com) gösterir.

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

• RegularPayment, SecurePayment ve CreateSavedCard artık Customer değil PaymentCustomer alır. Geçit ödemede ve kart saklamada gönderim adresini 422 ile reddettiği için shippingAddress taşıyabilen Customer bu isteklerden çıktı. new Customer(reference: …, billingAddress: …) yazan ödeme kodu new PaymentCustomer(billingAddress: …, reference: …) olmalıdır; billingAddress artık zorunludur. Sipariş ve abonelik Customer almaya devam eder.

1.0.3

Eklenenler:

• Müşteri kilidi ve müşteriye e-posta: CreateOrder, UpdateOrder, CreateSubscription ve UpdateSubscription locksCustomer ve emailsCustomer alır. Order ve Subscription yanıtları requiresShipping, locksCustomer ve emailsCustomer taşır.

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

• Ödeme linkinde emailsPayer → emailsCustomer. CreatePaymentLink, UpdatePaymentLink ve PaymentLink yanıtında alanın adı değişti; geçit eski emails_payer adını artık kabul etmez. emailsPayer: yazan kod emailsCustomer: olarak değişmelidir.
• UpdateOrder ve UpdateSubscription yapıcısında yeni alanlar clear'dan önce gelir. clear'ı konumsal argümanla geçen kod isimli argümana geçmelidir.

1.0.2

Eklenenler:

• retrieveLinkPayments() (retrieve-link-payments): linkte yapılan ödemeler, öteki sorgular gibi RetrieveLinkPayments::byToken(), byReference() (LINKPAY{n}), between() ya da latest() ile. Yanıt LinkPaymentList; her LinkPayment token, reference, paymentLink (token, reference), paymentProviderToken, status, items, subtotal, taxAmount, amount, discount, currency, customer (billingAddress), isTest, createdAt ve transaction taşır.
• linkPaymentToken: PaymentTransaction (ödeme yanıtlarındaki transaction), Transaction (retrievePayments() ve retrievePaymentLinks() içindeki denemeler) ve Webhook (bütün payment_link.* olayları) linkte alınan ödemede link ödemesinin token'ını verir.
• Ödeme linkinde seçimli tutar ve para birimi: CreatePaymentLink ve UpdatePaymentLink yeni alanlar alır: amountType, itemName, predefinedAmounts, taxRate, taxMode, currencyType, currencies, emailsPayer. PaymentLink yanıtı aynı alanları taşır. UpdatePaymentLink clear listesi artık item_name, predefined_amounts, tax_rate ve currencies alanlarını da boşaltabilir.
• discount: Order, Subscription ve LinkPayment ödeyenin ödeme sayfasında girdiği kuponu Discount (code, amount) olarak taşır; kupon yoksa null. Webhook gövdesinde yoktur.
• Yeni enum'lar: Enum\LinkPaymentStatus (Open, Paid), Enum\AmountType (Fixed, Custom, Predefined, PredefinedAndCustom), Enum\CurrencyType (Fixed, Selectable), Enum\TaxMode (Inclusive, Exclusive). Bilinmeyen değer, öteki enum'larda olduğu gibi null okunur.

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

• *`create-artık idempotent değil.**createOrder(),createSubscription()vecreatePaymentLink()aynıreferenceile çağrılsa da her seferinde yeni kayıt ve yeni token açar; eski kayıt güncellenmez, 422 de dönmez. Referans tekil değildir. Her create yanıtındaki token'ı saklayın ve değişikliğiupdate*()` ile token'la yapın.
• Link güncellemesi bekleyen ödemede reddedilmez. Bekleyen ödeme engeli yalnızca updateOrder() ve updateSubscription() için geçerlidir.
• CreatePaymentLink yapıcısında currency artık ilk parametre, items isteğe bağlı (Fixed dışındaki tiplerde gönderilmez). İsimli argümanla yazılmış kod etkilenmez; konumsal argümanla items, currency sırasında çağıran kod isimli argümana geçmelidir.
• UpdatePaymentLink yapıcısında yeni alanlar clear'dan önce gelir. clear'ı konumsal argümanla geçen kod isimli argümana geçmelidir.
• PaymentLink::$subtotal, $taxAmount, $amount artık ?string. Tutarı ödeyenin seçtiği linkte null gelir (eskiden boş dize okunuyordu).

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:

• Uç noktalar yeniden adlandırıldı. Her metot uç noktanın adını taşır: orderPayment() → createOrder(), subscriptionPayment() → createSubscription(), saveCard() → createSavedCard(), savedCards() → retrieveSavedCards(), defaultSavedCard() → updateSavedCard(), cancelSubscription() → updateSubscription(status: SubscriptionStatus::Cancelled), retrieveTransactions() → retrievePayments(). saveProduct() kalktı; kalemler isteğin içinde gönderilir.
• Tekil kaydı adlandıran istek alanı her yerde token. RefundPayment ve CancelPayment artık transactionToken değil token alır.
• Yanıtlar API JSON'unu birebir yansıtır. Ödeme yanıtında düz transactionToken / channelToken / channelReference yerine $payment->transaction->token vb.; transaction artık status, paymentStatus, securityType, amount, baseAmount, currency, installmentNumber, isTest, createdAt de taşır. Müşteri $payment->customer altındadır.
• Sabit kümeli alanlar tipli. Yanıtlarda currency, period, status (sipariş, abonelik, işlem), paymentStatus, securityType, refund->type, kart scheme ve type artık dize değil Gurmehub\Odemehub\Enum\* değerleridir (?Currency, ?OrderStatus, ?SubscriptionStatus, ?TransactionStatus, ?PaymentStatus, ?SecurityType, ?RefundType, ?CardScheme, ?CardType, ?Period). Karşılaştırmayı enum'la yapın ($order->status === OrderStatus::Paid), metin gerekiyorsa ->value kullanın. Geçit SDK'nın bilmediği yeni bir değer gönderirse alan çökmeden null olur.
• Müşteri: OrderDetails / SubscriptionDetails müşteriyi hem üstte (->customer) hem varlığın üzerinde (->order->customer, ->subscription->customer) taşır; listelerde her öğenin customer alanındadır.
• Kayıtlı kartlar müşteri referansıyla tutulur: RetrieveSavedCards email almaz, kart yanıtlarındaki customer yalnızca reference taşır. deleteSavedCard() delete-saved-card/{token} adresine gider.
• Ödeme linki: checkoutUrl link ödenemezken null; expiresAt ISO 8601 UTC; retrievePaymentLinks() son 50 denemeyi ve transactionsCount'u döner.
• Hatalar: güncellenen, silinen, iade ya da iptal edilen kaydın token'ı bulunamazsa NotFoundException (404) atılır; eskiden bu durum 422 dönüyordu. Sorgular bulunamayan kayıtta boş liste döner. Yeni istisnalar: ForbiddenException (403), NotFoundException (404), RateLimitException (429, retryAfter).
• Webhook: orderWebhook(), subscriptionWebhook(), transactionWebhook() yerine tek webhook() (ve verifyWebhook()); imza yöntem, yol, gövde ve zaman damgası üzerindendir. Gövde artık yalnızca token taşır (orderToken, paymentLinkToken, subscriptionToken, transactionToken); durum retrieve*() ile sorulur. Adresler panelde tanımlandığı için SecurePayment, CreateOrder, UpdateOrder, CreateSubscription, UpdateSubscription artık webhookUrl almaz.
• Kanal kalktı. Options artık channelToken almaz; isteklerde channelToken yoktur. Referans alanları channelReference yerine reference adını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlarda channelToken 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: retrievePayments(), retrieveOrders(), retrieveSubscriptions(), retrievePaymentLinks(), retrieveSavedCards(). İstek byToken(), byReference(), between() ya da latest() ile kurulur; yanıt her zaman listedir, bulunamayan kayıt 404 değil boş listedir.
• 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: taxRate isteğe bağlı (boşsa vergisiz); yeni saveAsProduct.
• Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur. NamedCustomer reference ve billingAddress alanları boş olabilir.
• Ödeme linki: retrievePaymentLinks() her linkte son 50 denemeyi ve transactionsCount'u PaymentLink üzerinde verir; PaymentLinkDetails yalnızca linki taşır.
• Kayıtlı kart: listede her kart kendi customer'ını taşır; SavedCardList::$customer kalktı. Ödeme yanıtındaki Transaction::$savedCard, kartın saklanması istendiyse saklanan kartı verir.

Örnekler

example/ klasöründe her uç nokta grubu için çalışan bir sayfa vardır. php -S localhost:8080 -t example ile sunun; kimlik bilgileri example/config.php içindedir ve ortam değişkenleriyle değiştirilir.