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.0</version>
</dependency>

Gradle:

implementation 'com.odemehub:java-sdk:1.0.0'

İstemci

import com.odemehub.Client;
import com.odemehub.Options;

Client client = new Client(Options.builder()
    .baseUrl("https://odeme.gurmehub.com")
    .team(System.getenv("ODEMEHUB_TEAM"))                  // Çalışma Alanı Kimliği
    .channelToken(System.getenv("ODEMEHUB_CHANNEL_TOKEN"))
    .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.
• İstek sınıfları com.odemehub.request, yanıt sınıfları com.odemehub.response, istisnalar com.odemehub.exception paketindedir. İstek ve yanıt sınıfları aynı adları taşır (request.SecurePayment / response.SecurePayment).
• Çok alanlı istekler builder ile, az alanlılar yapıcıyla kurulur. Zorunlu alan eksikse build() NullPointerException atar.

Müşteri ve kart

import com.odemehub.request.Card;
import com.odemehub.request.Customer;

var customer = Customer.builder()
    .channelReference("musteri-88")
    .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("Türkiye")
    // .tax(new TaxDetails("...", "...", "..."))
    .build();

var card = Card.builder()
    .holderName("AHMET YILMAZ")
    .number("5400360000000003")
    .securityCode("000")
    .expiryMonth("12")
    .expiryYear("2030")
    // .shouldSave(true)
    .build();

Regular ödeme

import com.odemehub.request.RegularPayment;

var payment = client.regularPayment(RegularPayment.builder()
    .channelReference("SIP-10231")
    .amount("450.00")
    .installmentNumber(1)
    .ip(request.getRemoteAddr())
    .customer(customer)
    .card(card)
    .build());

payment.getResult().isSuccessful();  // boolean
payment.getResult().getMessage();    // String, başarılıysa null
payment.getTransactionToken();
payment.getConversion();             // null olabilir
payment.getSavedCard();              // null olabilir

card ile savedCardToken birlikte verilir ya da hiçbiri verilmezse build() IllegalArgumentException atar.

3D Secure ödeme

import com.odemehub.request.SecurePayment;

var payment = client.securePayment(SecurePayment.builder()
    .channelReference("SIP-10232")
    .amount("450.00")
    .installmentNumber(1)
    .ip(request.getRemoteAddr())
    .callbackUrl("https://magazam.com/odeme/donus")
    .customer(customer)
    .card(card)
    .build());

if (payment.getResult().isSuccessful()) {
    return "redirect:" + payment.getRedirectUrl();
}

callbackUrl işleyicisi:

import com.odemehub.request.RetrievePayment;

@PostMapping("/odeme/donus")
public String odemeDonus(@RequestParam("transaction_token") String transactionToken) {
    var outcome = client.retrievePayment(new RetrievePayment(transactionToken));

    if (outcome.getResult().isSuccessful()) {
        // ödendi
    }
    // ...
}

Akış: Secure (3D) Ödeme.

Ödeme sorgusu

var payment = client.retrievePayment(new RetrievePayment(transactionToken));

İade ve iptal

import com.odemehub.request.CancelPayment;
import com.odemehub.request.RefundPayment;

var cancel = client.cancelPayment(new CancelPayment(transactionToken));
var refund = client.refundPayment(new RefundPayment(transactionToken, "100.00"));
// Kalanın tamamı: new RefundPayment(transactionToken)

refund.getType();    // "refund" | "cancel"
refund.getAmount();  // geri verilen tutar

Diğer uçlar

Metot	İstek
orderPayment	OrderPayment.builder() — channelReference, successUrl, customer, items(List<OrderItem>), cancelUrl, description, currency, paymentProviderToken. Kalem: OrderItem.of(ref) ya da OrderItem.builder().
subscriptionPayment	SubscriptionPayment.builder() — channelReference, items(List<SubscriptionItem>), successUrl, customer, cancelUrl, webhookUrl, paymentProviderToken. Kalem: SubscriptionItem.of(ref) ya da SubscriptionItem.builder().
retrieveSubscription / cancelSubscription	new RetrieveSubscription(token) / new CancelSubscription(token)
retrieveBin	RetrieveBin.builder() — bin, amount, paymentProviderToken, currency
saveProduct	SaveProduct.builder() — channelReference, name, type, amount, taxRate, period, currency, isActive
saveCard	SaveCard.builder() — customer, card, paymentProviderToken
savedCards	new SavedCards(new NamedCustomer(ref))
defaultSavedCard / deleteSavedCard	new DefaultSavedCard(new NamedCustomer(ref), savedCardToken) / new DeleteSavedCard(...)

Kanal alanı olan isteklerde channelToken(...) (builder) ya da yapıcının son parametresiyle istemcinin kanalı istek bazında değiştirilebilir. Örnekler her uç sayfasının SDK örnekleri bölümündedir.

Hata yönetimi

İstisnalar denetimsizdir (RuntimeException).

import com.odemehub.exception.AuthenticationException;
import com.odemehub.exception.OdemehubException;
import com.odemehub.exception.SignatureException;
import com.odemehub.exception.TransportException;
import com.odemehub.exception.UnexpectedResponseException;
import com.odemehub.exception.ValidationException;

try {
    client.regularPayment(paymentRequest);
} catch (ValidationException e) {
    e.getErrors();   // {transaction.amount=[...]}
} catch (AuthenticationException e) {
    // 401
} catch (UnexpectedResponseException e) {
    e.getStatus();   // ör. 403
} catch (SignatureException e) {
    // yanıtın imzası tutmadı
} catch (TransportException e) {
    // gateway'e ulaşılamadı; sonuç bilinmiyor
}

Abonelik webhook'u

Gövde ham (byte[]) okunmalıdır.

import com.odemehub.exception.SignatureException;

@PostMapping("/odemehub/abonelik")
public ResponseEntity<Void> abonelikBildirimi(
    @RequestBody byte[] payload,
    @RequestHeader(value = "X-Signature", required = false) String signature
) {
    com.odemehub.response.SubscriptionWebhook webhook;

    try {
        webhook = client.subscriptionWebhook(payload, signature);
    } catch (SignatureException e) {
        return ResponseEntity.badRequest().build();
    }

    if (webhook.isActive()) { /* webhook.getSubscription().getEndsAt() */ }
    else if (webhook.isPastDue()) { /* webhook.getSubscription().getCheckoutUrl() */ }
    else if (webhook.isCancelled()) { /* ... */ }
    else if (webhook.isEnded()) { /* ... */ }

    return ResponseEntity.ok().build();
}

Ayrıntılar: Abonelik Webhook'u.