Java SDK
Kurulum
Java 17 ve üzeri gerekir. İstekler java.net.http.HttpClient ile gönderilir; JSON için Jackson kullanılır.
Maven:
<dependency>
<groupId>com.odemehub</groupId>
<artifactId>java-sdk</artifactId>
<version>1.0.8</version>
</dependency>
Gradle:
implementation 'com.odemehub:java-sdk:1.0.8'
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 com.odemehub.Client;
import com.odemehub.Options;
Client client = new Client(Options.builder()
.baseUrl("https://sandbox.odemehub.com")
.team(System.getenv("ODEMEHUB_TEAM")) // Çalışma Alanı Kimliği
.apiKey(System.getenv("ODEMEHUB_API_KEY"))
.apiSecret(System.getenv("ODEMEHUB_API_SECRET"))
// .timeout(Duration.ofSeconds(30)) // varsayılan 1 dakika
.build());
- İstemci durum tutmaz; tek bir nesne bütün thread'lerde paylaşılabilir. Kendi
HttpClientnesneniznew Client(options, httpClient)ile verilebilir. - Her uç için uçla aynı adı taşıyan bir metot vardır:
create-order→createOrder(CreateOrder). Liste: SDK'lar. - İstek sınıfları
com.odemehub.request, yanıt sınıflarıcom.odemehub.response, sabit kümelercom.odemehub.enums, istisnalarcom.odemehub.exceptionpaketindedir. Çok alanlı istekler builder ile, az alanlılar yapıcıyla kurulur;Update*istekleribuilder(token)ile başlar ve bir alanı boşaltmak içinclear("description")alır. - Yanıtlar API JSON'unu birebir izler (
payment.getTransaction().getToken()). Sabit kümeli alanlar enum'dur; SDK'nın bilmediği bir değer gelirse alannullolur. - Tek bir kaydı adlandıran istek parametresi her zaman
token'dır.
Müşteri ve kart
import com.odemehub.request.Address;
import com.odemehub.request.Card;
import com.odemehub.request.PaymentCustomer;
var billingAddress = Address.builder()
.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")
// .companyTitle(...).taxNumber(...).taxOffice(...)
.build();
var customer = PaymentCustomer.builder()
.reference("musteri-88")
.billingAddress(billingAddress)
.build();
var card = Card.builder()
.holderName("AHMET YILMAZ")
.number("5400360000000003")
.securityCode("000")
.expiryMonth("12")
.expiryYear("2030")
.build();
Ödeme ve kart saklama istekleri PaymentCustomer alır; gönderim adresi yoktur. Fatura adresi zorunludur; Varsayılan Ödeyen açıksa billingAddress(...)'i ya da adresin alanlarından bazılarını vermeyebilirsiniz, eksikler varsayılan ödeyenden tamamlanır. RegularPayment ve SecurePayment builder'larında customer(...) da verilmeyebilir; CreateSavedCard'da customer(...) ve referans yine zorunludur. Sipariş ve abonelik Customer alır; orada billingAddress ve shippingAddress isteğe bağlıdır.
Regular ödeme
import com.odemehub.request.RegularPayment;
var payment = client.regularPayment(RegularPayment.builder()
.reference("SIP-10231")
.amount("450.00")
.installmentNumber(1)
.ip(request.getRemoteAddr())
.customer(customer)
.card(card)
.build());
if (payment.getResult().isSuccessful()) {
payment.getTransaction().getToken(); // iade, iptal ve sorgu için
payment.getTransaction().getPaymentStatus(); // PaymentStatus.PAID
}
3D Secure ödeme
import com.odemehub.request.RetrievePayments;
import com.odemehub.request.SecurePayment;
var payment = client.securePayment(SecurePayment.builder()
.reference("SIP-10231")
.amount("450.00")
.installmentNumber(1)
.ip(request.getRemoteAddr())
.callbackUrl("https://magazam.com/odeme/donus")
.customer(customer)
.card(card)
.build());
if (payment.getRedirectUrl() != null) {
return "redirect:" + payment.getRedirectUrl();
}
// callback_url işleyicisinde:
var payments = client.retrievePayments(RetrievePayments.byToken(transactionToken)).getPayments();
!payments.isEmpty() && payments.get(0).isSuccessful();
Sipariş, ödeme linki, abonelik, kayıtlı kart
import com.odemehub.request.CreateOrder;
import com.odemehub.request.Customer;
import com.odemehub.request.Item;
import com.odemehub.request.MaxInstallments;
import java.util.List;
var created = client.createOrder(CreateOrder.builder()
.reference("SIP-10233")
.successUrl("https://magazam.com/tesekkurler")
.items(List.of(Item.builder().name("Kahve makinesi").unitAmount("450.00").quantity(1).taxRate("20").build()))
.customer(Customer.builder().reference("musteri-88").billingAddress(billingAddress).build())
.requiresShipping(true) // ödeme sayfasında gönderim yöntemi seçilir, ücreti tutara eklenir
.locksCustomer(true) // müşteri bilgisi sorulmaz, gönderildiği gibi gösterilir
.emailsCustomer(true) // ödeme tamamlanınca fatura adresindeki e-postaya yazılır
.maxInstallments(MaxInstallments.builder().individual(1).commercial(3).build()) // bireysel kartta tek çekim, ticari kartta en çok 3 taksit
.build());
return "redirect:" + created.getOrder().getCheckoutUrl();
locksCustomer(true) eksiksiz fatura adresi ister; requiresShipping de açıksa gönderim adresi shippingAddress'ten, verilmezse fatura adresinden alınır. Aynı üç alan UpdateOrder, CreateSubscription ve UpdateSubscription builder'larında da vardır; Order ve Subscription yanıtları requiresShipping(), locksCustomer() ve emailsCustomer() ile verir. Ödeme linkinde yalnızca emailsCustomer 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
import com.odemehub.request.CancelPayment;
import com.odemehub.request.RefundPayment;
var refund = client.refundPayment(new RefundPayment(transactionToken, "100.00"));
refund.getRefund().getAmount();
client.cancelPayment(new CancelPayment(transactionToken));
Hata yönetimi
Gateway isteği reddederse istisna atılır; reddedilen ödeme, iade ya da kart saklama istisna değildir (getResult().isSuccessful() false). Bütün istisnalar denetimsizdir ve com.odemehub.exception.OdemehubException'dan türer.
import com.odemehub.exception.NotFoundException;
import com.odemehub.exception.OdemehubException;
import com.odemehub.exception.RateLimitException;
import com.odemehub.exception.ValidationException;
try {
client.regularPayment(payment);
} catch (ValidationException exception) {
exception.getErrors(); // {transaction.amount=[...]} (422)
} catch (RateLimitException exception) {
exception.getRetryAfter(); // 429; beklenecek saniye (Retry-After)
} catch (NotFoundException exception) {
// 404
} catch (OdemehubException exception) {
exception.getMessage(); // Türkçe
}
| İstisna | Durum |
|---|---|
AuthenticationException | 401 |
ForbiddenException | 403 |
NotFoundException | 404 |
ValidationException | 422 |
RateLimitException | 429 |
UnexpectedResponseException | Diğer kodlar (500 dahil); getStatus(). |
SignatureException | Yanıtın imzası tutmadı. |
TransportException | Gateway'e ulaşılamadı ya da yanıt okunamadı; sonuç bilinmiyor. |
Bkz. Hatalar.
1.0.8'deki değişiklikler
Eklenenler:
- İş ortağı istemcisi:
PartnerClient(PartnerOptions.builder():baseUrl,apiKey,apiSecret,timeout; takım yok) iş ortağının anahtarıyla/api/partner/uçlarını çağırır:createTeam,retrieveTeams(sayfalı;RetrieveTeams.all()ya dabySlugs(...),page(...),perPage(...)),updateTeamModules,deleteTeam. YanıtlarPartnerTeamDetails,PartnerTeamList(getPagination()) veDeletedTeam; çalışma alanıPartnerTeam.teamClient(PartnerTeam)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ındaForbiddenException):retrieveProviders,createPaymentProvider,retrievePaymentProviders,updatePaymentProvider,deletePaymentProvider,createWebhookEndpoint,retrieveWebhookEndpoints,updateWebhookEndpoint,deleteWebhookEndpoint,updateTeam,retrieveCheckoutDesign,updateCheckoutDesign(logo(null)vetermsUrl(null)kaldırır) vecreateLogo(CreateLogo.fromBytes(byte[])).RetrievePaymentProvidersveRetrieveWebhookEndpointsall()ya dabyTokens(...)ile kurulur. 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.builder().individual(...).commercial(...)ve sipariş, abonelik ve ödeme linki oluşturma/güncelleme builder'larındamaxInstallments(...);Order,SubscriptionvePaymentLinkyanıtlarındagetMaxInstallments()(yoksanull). GüncellemedeMaxInstallments.builder().build()sınırı kaldırır. Bkz. Taksit sınırı.
1.0.6'daki değişiklikler
Eklenenler:
- Banka hareketleri:
retrieveBanks,createBankAccount,retrieveBankAccounts,updateBankAccount,deleteBankAccount,retrieveBankTransactions; isteklerRetrieveBanks,CreateBankAccount,RetrieveBankAccounts,UpdateBankAccount,DeleteBankAccount,RetrieveBankTransactions, yanıtlarBankList,BankAccountDetails,BankAccountList,DeletedBankAccount,BankTransactionList(Pagination,BankTransaction). Bankanın reddettiği kimlik bilgisi istisna değildir:getResult().isSuccessful()false,getBankAccount()null. Bkz. Banka Hareketleri. - Sorgularda sayfalama: altı sorgu isteğine
page(int)veperPage(int)(en çok 250); liste yanıtlarınagetPagination()(Pagination,hasMorePages()). 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,NotFoundExceptionyalnızca token'lı güncelleme/silme/iade/iptalde, en çok 100 kalem, gönderim adresinde firma alanları422. 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.builder().build()billingAddress(...)verilmeden de kurulur;RegularPaymentveSecurePaymentbuilder'larındacustomer(...)artık zorunlu değildir. Verilmeyen adres ya da müşteri gövdeye yazılmaz. Varsayılan Ödeyen açıksa eksikler varsayılan ödeyenden tamamlanır; kapalıyken sekiz kişi alanı yine zorunludur. Eksik adres ya da müşteri artıkbuild()'deNullPointerExceptionatmaz, geçittenValidationException(422) döner.CreateSavedCard'dacustomer(...)ve referans zorunlu kalır. 403anlatımı:ForbiddenExceptionaçı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ı.CardveCreateSubscriptionaçıklamaları Kayıtlı Kartlar modülünü anar. Kod değişmedi; bkz.403.
Kırıcı değişiklik yoktur; 1.0.4 kodu değişmeden çalışır.
1.0.4'teki değişiklikler
Eklenenler:
- Sandbox'la başlayan kurulum: README ve
Optionsaçıklaması entegrasyonuhttps://sandbox.odemehub.comüzerinde kurar; canlıya çıkarkenbaseUrlhttps://app.odemehub.comolur. Bkz. Ortamlar ve Adresler. PaymentCustomer: ödemenin ve kart saklamanın müşterisi;PaymentCustomer.builder()yalnızcabillingAddress(zorunlu) vereferencealı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;shippingAddresstaşıyabilenCustomerbu isteklerden çıktı. Ödeme kodunda.customer(Customer.builder()…)→.customer(PaymentCustomer.builder()…).CreateOrderveCreateSubscriptionCustomeralmaya devam eder.
1.0.3'teki değişiklikler
- Müşteri kilidi ve müşteriye e-posta:
CreateOrder,UpdateOrder,CreateSubscriptionveUpdateSubscriptionbuilder'larındalocksCustomerveemailsCustomer.OrderveSubscriptionyanıtlarındarequiresShipping(),locksCustomer()veemailsCustomer(). Bkz.create-orderve E-postalar. - Kırıcı: ödeme linkinde
emailsPayer→emailsCustomer.CreatePaymentLinkveUpdatePaymentLinkbuilder'larında vePaymentLinkyanıtında alanın adı değişti; gateway eskiemails_payeradını kabul etmez.
1.0.2'deki değişiklikler
Eklenenler:
- Link ödemeleri:
retrieveLinkPayments(RetrieveLinkPayments)(byToken,LINKPAY{n}ilebyReference,between,latest). YanıtLinkPaymentList(paid()); herLinkPaymentlinkigetPaymentLinkToken()/getPaymentLinkReference()ile verir, ayrıca kalemleri, tutarları,getDiscount(),getCustomer(),getTransaction()veisPaid()taşır. Yeni enum:LinkPaymentStatus(OPEN,PAID). Bkz.retrieve-link-payments. getLinkPaymentToken():PaymentTransaction,TransactionveWebhooklinkte alınan ödemede link ödemesinin token'ını verir.- Ödeme linki alanları:
CreatePaymentLinkveUpdatePaymentLinkbuilder'larındaamountType,itemName,predefinedAmounts,taxRate,taxMode,currencyType,currenciesveemailsPayer(1.0.3'teemailsCustomeroldu);PaymentLinkyanıtında aynı alanlar. Yeni enum'lar:AmountType,CurrencyType,TaxMode.UpdatePaymentLink.clear(...)item_name,predefined_amounts,tax_ratevecurrenciesalanlarını da boşaltır. getDiscount():Order,SubscriptionveLinkPaymentüzerindeDiscount(getCode(),getAmount()); kupon yoksanull. Webhook gövdesinde yoktur.
Küçük kırıcı değişiklikler:
create*her çağrıda yeni kayıt açar.createOrder,createSubscriptionvecreatePaymentLinkaynıreferenceile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt yeniden yazılmaz,422dönmez. Yanıttaki token'ı saklayın, değişiklik içinupdate*(token)kullanın. Bkz. Aynı referansla tekrarlanancreate-*istekleri.CreatePaymentLink.itemsisteğe bağlıdır:build()kalemsiz linkte artıkNullPointerExceptionfırlatmaz; kalemler yalnızcaFIXEDtipte gerekir ve eksikse gatewayValidationExceptionile reddeder.- Link tutarları
nullolabilir: tutarı ödeyenin belirlediği linktePaymentLink.getSubtotal(),getTaxAmount()vegetAmount()boş dizgi yerinenulldöner. - Link güncellemesi: sonuçlanmamış ödemesi olan link de değiştirilebilir.
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: İmza zaman damgası, metot, yol ve gövdeyi kapsar ve
X-Timestampbaşlığıyla gider. 1.0.0 bugünkü gateway'le konuşamaz. - Kaldırılan uçlar:
orderPayment,subscriptionPayment,saveProduct,cancelSubscription,retrieveTransactions,saveCard,savedCards,defaultSavedCard. YerlerinecreateOrder,createSubscription,updateSubscription(...status(SubscriptionStatus.CANCELLED)),retrievePayments/retrievePayments,createSavedCard,retrieveSavedCards,updateSavedCard. - Yeni metotlar: ödeme linki uçları, bütün güncelleme uçları ve her kaynakta tek
retrieve*sorgusu. - Müşteri:
Customerartıkreference,billingAddressveshippingAddress(Address) taşır;reference, düz adres alanları veTaxDetailskalktı. - Kalemler:
OrderItem/SubscriptionItemyerine ad, fiyat, adet ve KDV oranı zorunlu tekItem. - Token: Tek kaydı adlandıran her istek parametresi
token'dır (new RefundPayment(token),UpdateOrder.builder(token)). - Yanıtlar iç içe: Ödeme bilgisi
payment.getTransaction(), iadegetRefund()altında; ödeme linkinin işlemleriPaymentLinkDetailsüzerindedir. Sabit kümeli alanlarcom.odemehub.enumsenum'larıdır. - 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). - Kanal kalktı.
Options.builder().channelToken(...), isteklerdekichannelToken(...)veChannelMessageyoktur. Referans alanlarıchannelReferenceyerinereferenceadını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlardagetChannelToken()yoktur,getChannelReference()yerinegetReference(). Geri dönüşte tarayıcıchannel_referencedeğilreferencePOST eder. - Sorgular tek uçta. Her kaynakta tek sorgu metodu vardır:
retrievePayments,retrieveOrders,retrieveSubscriptions,retrievePaymentLinks,retrieveSavedCards. İstekbyToken,byReference,betweenya dalatestile kurulur; yanıt her zaman listedir, bulunamayan kayıtNotFoundExceptiondeğ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:
taxRateisteğe bağlı; yenisaveAsProduct. - Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur.
NamedCustomer.getReference()vegetBillingAddress()nullolabilir. - Ödeme linki: son 50 deneme ve
getTransactionsCount()retrievePaymentLinksyanıtında herPaymentLinküzerindedir;PaymentLinkDetailsyalnızca linki taşır. - Kayıtlı kart: listede her kart kendi
getCustomer()'ını taşır;SavedCardList.getCustomer()kalktı, varsayılan kartdefaultCard()ile alınır. Listelenen ödemedegetSavedCard(), 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 com.odemehub.response.Webhook döner. Nesne yalnızca token taşır: getOrderToken(), getPaymentLinkToken(), getLinkPaymentToken(), getSubscriptionToken(), getTransactionToken(). Kararı bu token'larla çağırdığınız retrieve yanıtına göre verin. Yalnızca imzayı doğrulamak için verifyWebhook() kullanılır.
Olaylar, adres tanımlama ve her dildeki örnek işleyici: Webhook.