يوفر SDK جافا وصولاً مريحًا وسهل الاستخدام إلى واجهة برمجة تطبيقات REST الخاصة بمدفوعات دودي للتطبيقات المكتوبة بلغة جافا. يستخدم ميزات محددة لجافا مثل Optional وStream وCompletableFuture لتطوير جافا الحديث.
التثبيت
Maven
أضف الاعتماد إلى pom.xml:
< dependency >
< groupId > com.dodopayments.api </ groupId >
< artifactId > dodo-payments-java </ artifactId >
< version > 1.61.5 </ version >
</ dependency >
Gradle
أضف الاعتماد إلى build.gradle:
implementation ( "com.dodopayments.api:dodo-payments-java:1.61.5" )
استخدم دائمًا أحدث إصدار من SDK للوصول إلى أحدث ميزات مدفوعات دودي. تحقق من Maven Central للحصول على أحدث إصدار.
يدعم SDK جافا 8 وجميع الإصدارات اللاحقة، بما في ذلك جافا 11 و17 و21.
البداية السريعة
قم بتهيئة العميل وإنشاء جلسة دفع:
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionRequest;
import com.dodopayments.api.models.checkoutsessions.CheckoutSessionResponse;
// Configure using environment variables (DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_BASE_URL)
// Or system properties (dodopayments.apiKey, dodopayments.baseUrl)
DodoPaymentsClient client = DodoPaymentsOkHttpClient . fromEnv ();
CheckoutSessionRequest params = CheckoutSessionRequest . builder ()
. addProductCart ( CheckoutSessionRequest . ProductCart . builder ()
. productId ( "product_id" )
. quantity ( 1 )
. build ())
. build ();
CheckoutSessionResponse checkoutSessionResponse = client . checkoutSessions (). create (params);
System . out . println ( checkoutSessionResponse . sessionId ());
قم دائمًا بتخزين مفاتيح API الخاصة بك بشكل آمن باستخدام متغيرات البيئة أو خصائص النظام أو نظام إدارة التكوين الآمن. لا تقم بتشفيرها في شفرتك المصدرية.
الميزات الأساسية
أمان النوع واجهة برمجة تطبيقات ذات نوع محدد مع أمان في وقت الترجمة
آمن للخيوط آمن للاستخدام المتزامن في التطبيقات متعددة الخيوط
نمط البناء نمط بناء بديهي لبناء الطلبات
دعم غير متزامن دعم CompletableFuture للعمليات غير المتزامنة
التكوين
متغيرات البيئة
قم بالتكوين باستخدام متغيرات البيئة أو خصائص النظام:
DODO_PAYMENTS_API_KEY = your_api_key_here
DODO_PAYMENTS_BASE_URL = https://live.dodopayments.com
// Automatically reads from environment variables
DodoPaymentsClient client = DodoPaymentsOkHttpClient . fromEnv ();
التكوين اليدوي
قم بالتكوين يدويًا مع جميع الخيارات:
import java.time.Duration;
DodoPaymentsClient client = DodoPaymentsOkHttpClient . builder ()
. bearerToken ( "your_api_key_here" )
. baseUrl ( "https://live.dodopayments.com" )
. maxRetries ( 4 )
. timeout ( Duration . ofSeconds ( 30 ))
. responseValidation ( true )
. build ();
وضع الاختبار
قم بالتكوين لبيئة الاختبار/الصندوق الرمل:
DodoPaymentsClient testClient = DodoPaymentsOkHttpClient . builder ()
. fromEnv ()
. testMode ()
. build ();
العمليات الشائعة
إنشاء جلسة دفع
قم بإنشاء جلسة دفع:
CheckoutSessionRequest params = CheckoutSessionRequest . builder ()
. addProductCart ( CheckoutSessionRequest . ProductCart . builder ()
. productId ( "prod_123" )
. quantity ( 1 )
. build ())
. returnUrl ( "https://yourdomain.com/return" )
. build ();
CheckoutSessionResponse session = client . checkoutSessions (). create (params);
System . out . println ( "Checkout URL: " + session . url ());
إدارة العملاء
قم بإنشاء واسترجاع معلومات العملاء:
import com.dodopayments.api.models.customers.Customer;
import com.dodopayments.api.models.customers.CustomerCreateParams;
// Create a customer
CustomerCreateParams createParams = CustomerCreateParams . builder ()
. email ( "[email protected] " )
. name ( "John Doe" )
. putMetadata ( "user_id" , "12345" )
. build ();
Customer customer = client . customers (). create (createParams);
// Retrieve customer
Customer retrieved = client . customers (). retrieve ( "cus_123" );
System . out . println ( "Customer: " + retrieved . name () + " (" + retrieved . email () + ")" );
التعامل مع الاشتراكات
قم بإنشاء وإدارة الاشتراكات المتكررة:
import com.dodopayments.api.models.subscriptions. * ;
// Create a subscription
SubscriptionNewParams subscriptionParams = SubscriptionNewParams . builder ()
. customerId ( "cus_123" )
. productId ( "prod_456" )
. priceId ( "price_789" )
. build ();
Subscription subscription = client . subscriptions (). create (subscriptionParams);
// Charge subscription
SubscriptionChargeParams chargeParams = SubscriptionChargeParams . builder ()
. amount ( 1000 )
. build ();
SubscriptionChargeResponse chargeResponse = client . subscriptions ()
. charge ( subscription . id (), chargeParams);
الفوترة بناءً على الاستخدام
تكوين العدادات
قم بإنشاء وإدارة العدادات لتتبع الاستخدام:
import com.dodopayments.api.models.meters. * ;
// Create API calls meter
MeterCreateParams apiMeterParams = MeterCreateParams . builder ()
. name ( "API Requests" )
. eventName ( "api_request" )
. aggregation ( "count" )
. putMetadata ( "category" , "api_usage" )
. build ();
Meter apiMeter = client . meters (). create (apiMeterParams);
System . out . println ( "Meter created: " + apiMeter . meterId ());
// List all meters
client . meters (). list ()
. autoPager ()
. forEach (m -> System . out . println ( "Meter: " + m . name () + " - " + m . aggregation ()));
استيعاب أحداث الاستخدام
تتبع الأحداث المخصصة:
import com.dodopayments.api.models.usageevents. * ;
import java.time.OffsetDateTime;
// Ingest single event
UsageEventIngestParams singleEventParams = UsageEventIngestParams . builder ()
. addEvent ( UsageEventIngestParams . Event . builder ()
. eventId ( "api_call_" + System . currentTimeMillis ())
. customerId ( "cus_abc123" )
. eventName ( "api_request" )
. timestamp ( OffsetDateTime . now ())
. putMetadata ( "endpoint" , "/api/v1/users" )
. putMetadata ( "method" , "GET" )
. putMetadata ( "tokens_used" , "150" )
. build ())
. build ();
UsageEventIngestResponse response = client . usageEvents (). ingest (singleEventParams);
System . out . println ( "Processed: " + response . processedEvents ());
استيعاب الأحداث دفعة واحدة
استيعاب عدة أحداث بكفاءة (حد أقصى 1000 لكل طلب):
UsageEventIngestParams . Builder batchBuilder = UsageEventIngestParams . builder ();
for ( int i = 0 ; i < 100 ; i ++ ) {
batchBuilder . addEvent ( UsageEventIngestParams . Event . builder ()
. eventId ( "batch_event_" + i + "_" + System . currentTimeMillis ())
. customerId ( "cus_abc123" )
. eventName ( "video_transcode" )
. timestamp ( OffsetDateTime . now (). minusMinutes (i))
. putMetadata ( "video_id" , "video_" + i)
. putMetadata ( "duration_seconds" , String . valueOf ( 120 + i))
. build ());
}
UsageEventIngestResponse batchResponse = client . usageEvents (). ingest ( batchBuilder . build ());
System . out . println ( "Batch processed: " + batchResponse . processedEvents () + " events" );
معالجة الأخطاء
معالجة شاملة للأخطاء لمختلف السيناريوهات:
import com.dodopayments.api.errors. * ;
try {
Payment payment = client . payments (). retrieve ( "pay_invalid" );
} catch ( NotFoundException e ) {
System . err . println ( "Payment not found: " + e . getMessage ());
} catch ( UnauthorizedException e ) {
System . err . println ( "Authentication failed: " + e . getMessage ());
} catch ( PermissionDeniedException e ) {
System . err . println ( "Permission denied: " + e . getMessage ());
} catch ( BadRequestException e ) {
System . err . println ( "Invalid request: " + e . getMessage ());
} catch ( UnprocessableEntityException e ) {
System . err . println ( "Validation error: " + e . getMessage ());
} catch ( RateLimitException e ) {
System . err . println ( "Rate limit exceeded: " + e . getMessage ());
// SDK automatically retries with backoff
} catch ( InternalServerException e ) {
System . err . println ( "Server error: " + e . getMessage ());
} catch ( DodoPaymentsServiceException e ) {
System . err . println ( "API error: " + e . statusCode () + " - " + e . getMessage ());
}
يقوم SDK تلقائيًا بإعادة محاولة الطلبات عند حدوث أخطاء في الاتصال، 408، 409، 429، وأخطاء 5xx مع تراجع أسي.
العمليات غير المتزامنة
استخدم CompletableFuture للعمليات غير المتزامنة:
import java.util.concurrent.CompletableFuture;
CompletableFuture < CheckoutSessionResponse > future = client . async ()
. checkoutSessions ()
. create (params);
// Handle response asynchronously
future . thenAccept (response -> {
System . out . println ( "Session created: " + response . sessionId ());
}). exceptionally (ex -> {
System . err . println ( "Error: " + ex . getMessage ());
return null ;
});
تكامل Spring Boot
فئة التكوين
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@ Configuration
public class DodoPaymentsConfig {
@ Value ( "${dodo.api.key}" )
private String apiKey ;
@ Value ( "${dodo.environment:sandbox}" )
private String environment ;
@ Bean
public DodoPaymentsClient dodoPayments () {
return DodoPaymentsOkHttpClient . builder ()
. bearerToken (apiKey)
. baseUrl ( environment . equals ( "live" )
? "https://live.dodopayments.com"
: "https://sandbox.dodopayments.com" )
. build ();
}
}
طبقة الخدمة
import com.dodopayments.api.client.DodoPaymentsClient;
import com.dodopayments.api.models.checkoutsessions. * ;
import org.springframework.stereotype.Service;
@ Service
public class PaymentService {
private final DodoPaymentsClient client ;
public PaymentService ( DodoPaymentsClient client ) {
this . client = client;
}
public CheckoutSessionResponse createCheckout ( List < CheckoutSessionRequest . ProductCart > items ) {
CheckoutSessionRequest params = CheckoutSessionRequest . builder ()
. productCart (items)
. returnUrl ( "https://yourdomain.com/return" )
. build ();
return client . checkoutSessions (). create (params);
}
}
الموارد
الدعم
هل تحتاج إلى مساعدة بشأن SDK جافا؟
المساهمة
نرحب بالمساهمات! تحقق من إرشادات المساهمة للبدء.