Ana içeriğe geç

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 HttpClient nesneniz new 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ümeler com.odemehub.enums, istisnalar com.odemehub.exception paketindedir. Çok alanlı istekler builder ile, az alanlılar yapıcıyla kurulur; Update* istekleri builder(token) ile başlar ve bir alanı boşaltmak için clear("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 alan null olur.
  • 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")
.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
}
İstisnaDurum
AuthenticationException401
ForbiddenException403
NotFoundException404
ValidationException422
RateLimitException429
UnexpectedResponseExceptionDiğer kodlar (500 dahil); getStatus().
SignatureExceptionYanıtın imzası tutmadı.
TransportExceptionGateway'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 da bySlugs(...), page(...), perPage(...)), updateTeamModules, deleteTeam. Yanıtlar PartnerTeamDetails, PartnerTeamList (getPagination()) ve DeletedTeam; çalışma alanı PartnerTeam. teamClient(PartnerTeam) açılan çalışma alanının Client'ını kurar. Bkz. İş Ortakları.
  • Yalnızca iş ortağı çalışma alanlarına açık uçlar (Client üzerinde; başka çalışma alanında ForbiddenException): retrieveProviders, createPaymentProvider, retrievePaymentProviders, updatePaymentProvider, deletePaymentProvider, createWebhookEndpoint, retrieveWebhookEndpoints, updateWebhookEndpoint, deleteWebhookEndpoint, updateTeam, retrieveCheckoutDesign, updateCheckoutDesign (logo(null) ve termsUrl(null) kaldırır) ve createLogo (CreateLogo.fromBytes(byte[])). RetrievePaymentProviders ve RetrieveWebhookEndpoints all() ya da byTokens(...) ile kurulur. Yanıtlar ProviderList, PaymentProviderDetails, PaymentProviderList, DeletedPaymentProvider, WebhookEndpointDetails, WebhookEndpointList, DeletedWebhookEndpoint, TeamDetails, CheckoutDesignDetails ve LogoDetails. 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ında maxInstallments(...); Order, Subscription ve PaymentLink yanıtlarında getMaxInstallments() (yoksa null). Güncellemede MaxInstallments.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; istekler RetrieveBanks, CreateBankAccount, RetrieveBankAccounts, UpdateBankAccount, DeleteBankAccount, RetrieveBankTransactions, yanıtlar BankList, 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) ve perPage(int) (en çok 250); liste yanıtlarına getPagination() (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ı varsa pagination toplamı 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 .test dahil), Item.image http ya da https, NotFoundException yalnı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:

  • RefundStatus kaldı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; RegularPayment ve SecurePayment builder'larında customer(...) 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ık build()'de NullPointerException atmaz, geçitten ValidationException (422) döner. CreateSavedCard'da customer(...) ve referans zorunlu kalır.
  • 403 anlatımı: ForbiddenException açı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 ve CreateSubscription açı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 Options açıklaması entegrasyonu https://sandbox.odemehub.com üzerinde kurar; canlıya çıkarken baseUrl https://app.odemehub.com olur. Bkz. Ortamlar ve Adresler.
  • PaymentCustomer: ödemenin ve kart saklamanın müşterisi; PaymentCustomer.builder() yalnızca billingAddress (zorunlu) ve reference alı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, SecurePayment ve CreateSavedCard Customer değil PaymentCustomer alır. Gateway ödemede ve kart saklamada gönderim adresini 422 ile reddeder; shippingAddress taşıyabilen Customer bu isteklerden çıktı. Ödeme kodunda .customer(Customer.builder()…) → .customer(PaymentCustomer.builder()…). CreateOrder ve CreateSubscription Customer almaya devam eder.

1.0.3'teki değişiklikler​

  • Müşteri kilidi ve müşteriye e-posta: CreateOrder, UpdateOrder, CreateSubscription ve UpdateSubscription builder'larında locksCustomer ve emailsCustomer. Order ve Subscription yanıtlarında requiresShipping(), locksCustomer() ve emailsCustomer(). Bkz. create-order ve E-postalar.
  • Kırıcı: ödeme linkinde emailsPayer → emailsCustomer. CreatePaymentLink ve UpdatePaymentLink builder'larında ve PaymentLink yanıtında alanın adı değişti; gateway eski emails_payer adını kabul etmez.

1.0.2'deki değişiklikler​

Eklenenler:

  • Link ödemeleri: retrieveLinkPayments(RetrieveLinkPayments) (byToken, LINKPAY{n} ile byReference, between, latest). Yanıt LinkPaymentList (paid()); her LinkPayment linki getPaymentLinkToken() / getPaymentLinkReference() ile verir, ayrıca kalemleri, tutarları, getDiscount(), getCustomer(), getTransaction() ve isPaid() taşır. Yeni enum: LinkPaymentStatus (OPEN, PAID). Bkz. retrieve-link-payments.
  • getLinkPaymentToken(): PaymentTransaction, Transaction ve Webhook linkte alınan ödemede link ödemesinin token'ını verir.
  • Ödeme linki alanları: CreatePaymentLink ve UpdatePaymentLink builder'larında amountType, itemName, predefinedAmounts, taxRate, taxMode, currencyType, currencies ve emailsPayer (1.0.3'te emailsCustomer oldu); PaymentLink yanıtında aynı alanlar. Yeni enum'lar: AmountType, CurrencyType, TaxMode. UpdatePaymentLink.clear(...) item_name, predefined_amounts, tax_rate ve currencies alanlarını da boşaltır.
  • getDiscount(): Order, Subscription ve LinkPayment üzerinde Discount (getCode(), getAmount()); kupon yoksa null. Webhook gövdesinde yoktur.

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

  • create* her çağrıda yeni kayıt açar. createOrder, createSubscription ve createPaymentLink aynı reference ile çağrılsa da yeni kayıt ve yeni token döner; önceki kayıt yeniden yazılmaz, 422 dönmez. Yanıttaki token'ı saklayın, değişiklik için update*(token) kullanın. Bkz. Aynı referansla tekrarlanan create-* istekleri.
  • CreatePaymentLink.items isteğe bağlıdır: build() kalemsiz linkte artık NullPointerException fırlatmaz; kalemler yalnızca FIXED tipte gerekir ve eksikse gateway ValidationException ile reddeder.
  • Link tutarları null olabilir: tutarı ödeyenin belirlediği linkte PaymentLink.getSubtotal(), getTaxAmount() ve getAmount() boş dizgi yerine null dö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-Timestamp baş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. Yerlerine createOrder, 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: Customer artık reference, billingAddress ve shippingAddress (Address) taşır; reference, düz adres alanları ve TaxDetails kalktı.
  • Kalemler: OrderItem / SubscriptionItem yerine ad, fiyat, adet ve KDV oranı zorunlu tek Item.
  • 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(), iade getRefund() altında; ödeme linkinin işlemleri PaymentLinkDetails üzerindedir. Sabit kümeli alanlar com.odemehub.enums enum'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(...), isteklerdeki channelToken(...) ve ChannelMessage yoktur. Referans alanları channelReference yerine reference adını taşır (ödeme, sipariş, abonelik, link, kalem); yanıtlarda getChannelToken() yoktur, getChannelReference() yerine getReference(). 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 NotFoundException değil boş listedir. GET isteği kalmadı.
  • 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ı; yeni saveAsProduct.
  • Müşteri: referans gönderilmeyebilir; o zaman müşteri kaydedilmez ve kart saklanamaz. Abonelikte ve kart saklamada zorunludur. NamedCustomer.getReference() ve getBillingAddress() null olabilir.
  • Ödeme linki: son 50 deneme ve getTransactionsCount() retrievePaymentLinks yanıtında her PaymentLink üzerindedir; PaymentLinkDetails yalnızca linki taşır.
  • Kayıtlı kart: listede her kart kendi getCustomer()'ını taşır; SavedCardList.getCustomer() kalktı, varsayılan kart defaultCard() ile alınır. Listelenen ödemede getSavedCard(), 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.