يوفر هذا المستودع وثائق خطوة بخطوة لـ Android SDK الأصلي لـ SumUp، والتي تمكنك من دمج محطة (محطات) البطاقة الخاصة بنا ومنصة الدفع الخاصة بها لقبول مدفوعات بطاقات الائتمان والخصم (بما في ذلك VISA وMasterCard وAmerican Express والمزيد). يتصل SDK بشفافية مع محطة (محطات) البطاقة عبر البلوتوث (BLE 4.0). عند بدء عملية الدفع، يقوم SDK بإرشاد المستخدم الخاص بك باستخدام الشاشات المناسبة خلال كل خطوة من خطوات عملية الدفع. وكجزء من العملية، يوفر SumUp أيضًا شاشة إعداد محطة البطاقة، إلى جانب شاشة التحقق من توقيع حامل البطاقة. يتم إرجاع نتيجة الخروج مع البيانات ذات الصلة لسجلاتك.
لا يتم تمرير أي بيانات حساسة للبطاقة إلى هاتف التاجر أو تخزينها عليه. يتم تشفير جميع البيانات بواسطة محطة البطاقة، والتي تم اعتمادها بالكامل وفقًا لأعلى معايير الصناعة (PCI، وEMV I & II، وVisa، وMasterCard، وAmex).
لمزيد من المعلومات حول منتجات مطوري SumUp، يرجى الرجوع إلى وثائق SumUp API الخاصة بنا.
minSdkVersion
26 أو إصدار أحدثtargetSDK
31 أو الأحدثأضف المستودع إلى تبعيات gradle الخاصة بك:
allprojects {
repositories {
maven { url ' https://maven.sumup.com/releases ' }
}
}
أضف التبعية إلى الوحدة النمطية:
implementation ' com.sumup:merchant-sdk:5.0.3 '
قم بتهيئة مكونات SumUp في تطبيقك:
public class SampleApplication extends Application {
@ Override
public void onCreate () {
super . onCreate ();
SumUpState . init ( this );
}
}
قبل استدعاء أي من ميزات SumUp SDK، يجب تسجيل الدخول إلى حساب تاجر SumUp المسجل. يرجى الانتقال إلى https://me.sumup.com/developers لاسترداد مفتاح الشريك التابع الخاص بك عن طريق إدخال معرف التطبيق الخاص بتطبيقك. (على سبيل المثال com.sumup.sdksampleapp)
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );
ملاحظة: من الممكن أيضًا تسجيل الدخول إلى حساب باستخدام رمز مميز، دون قيام المستخدم بإدخال بيانات اعتماد تسجيل الدخول الخاصة بـ SumUp في SDK. يرجى الرجوع إلى قسم المصادقة الشفافة
بمجرد تسجيل الدخول، يمكنك البدء في استخدام SumUp SDK لقبول مدفوعات البطاقة. إذا لم يتم تسجيل الدخول إلى أي حساب، فسيتم إرجاع SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN
.
SumUpPayment payment = SumUpPayment . builder ()
// mandatory parameters
. total ( new BigDecimal ( "1.12" )) // minimum 1.00
. currency ( SumUpPayment . Currency . EUR )
// optional: to be used only if the card reader supports the feature, what can be checked with `SumUpApi.isTipOnCardReaderAvailable()`
. tipOnCardReader ()
// optional: include a tip amount in addition to the total, ignored if `tipOnCardReader()` is present
. tip ( new BigDecimal ( "0.10" ))
// optional: add details
. title ( "Taxi Ride" )
. receiptEmail ( "[email protected]" )
. receiptSMS ( "+3531234567890" )
// optional: Add metadata
. addAdditionalInfo ( "AccountId" , "taxi0334" )
. addAdditionalInfo ( "From" , "Paris" )
. addAdditionalInfo ( "To" , "Berlin" )
// optional: foreign transaction ID, must be unique!
. foreignTransactionId ( UUID . randomUUID (). toString ()) // can not exceed 128 chars
// optional: skip the success screen
. skipSuccessScreen ()
// optional: skip the failed screen
. skipFailedScreen ()
. build ();
SumUpAPI . checkout ( MainActivity . this , payment , 2 );
@ Override
protected void onActivityResult ( int requestCode , int resultCode , Intent data ) {
if ( requestCode == 2 && data != null ) {
// Handle the response here
}
}
تتوفر عدة حقول استجابة عند استدعاء نشاط رد الاتصال:
يتم توفير إشارات الاستجابة داخل الحزمة التي يتم إرجاعها إلى نشاط رد الاتصال:
int resultCode = getIntent (). getExtras (). getInt ( SumUpAPI . Response . RESULT_CODE );
عندما يقوم التاجر بتسجيل الدخول، يمكنك فتح هذا النشاط للوصول إلى جميع الإعدادات والخيارات المتعلقة بقارئ البطاقات.
SumUpAPI . openCardReaderPage ( MainActivity . this , 4 );
يوفر prepareForCheckout()
إمكانية توصيل قارئ البطاقة قبل بدء عملية الدفع مما يؤدي إلى تسريع وقت الخروج الإجمالي.
لاستدعاء هذه الطريقة، يجب على المستخدم تسجيل الدخول باستخدام حساب SumUp ويجب إعداد قارئ البطاقات الخاص به بالفعل. بعد ذلك، اتصل prepareForCheckout()
قبل بدء عملية الدفع.
ملاحظة: تظل قارئات بطاقات Air وSolo متصلة عبر BLE بعد كل معاملة أثناء استخدام
prepareForCheckout()
عندما ينقطع اتصال قارئ البطاقة (على سبيل المثال، يكون القارئ خارج النطاق، أو يفقد التطبيق المضيف التركيز، أو يتم إيقاف تشغيل القارئ).
عند إعداد كائن SumUpPayment
، يمكن تضمين المعلمات الاختيارية التالية:
يمكن معالجة مبلغ الإكرامية بالإضافة إلى total
باستخدام معلمة tip
. سيتم بعد ذلك عرض مبلغ الإكرامية أثناء عملية الدفع وإدراجه في الرد. يرجى ملاحظة أنه لا يمكن تغيير مبلغ الإكرامية أثناء/بعد الخروج.
يتيح ذلك للعميل إضافة إكرامية مباشرة على قارئ البطاقة، بدلاً من المطالبة بمبلغ الإكرامية على جهاز Android.
يمكن المطالبة بمبلغ البقشيش مباشرة في قارئ البطاقة باستخدام معلمة tipOnCardReader
، إذا كان قارئ البطاقة يدعم البقشيش. انظر المثال هنا للحصول على الحقل tipOnCardReader
.
ملاحظة: لا تدعم كافة أجهزة قراءة البطاقات هذه الميزة. لمعرفة ما إذا كانت الميزة مدعومة لقارئ البطاقات المحفوظة مؤخرًا، يجب عليك دائمًا التحقق من
SumUpApi.isTipOnCardReaderAvailable()
. يجب عليك التعامل مع هذه الحالة بنفسك لتجنب مطالبتك بأي معلومات. يرجى أيضًا ملاحظة أنه إذا تم استدعاء كلtip
tipOnCardReader
، فسيتم أخذ مبلغtipOnCardReader
فقط في الاعتبار أثناء الدفع إذا كان متاحًا.
تتيح لك ميزة configureRetryPolicy()
تعيين معلمات إعادة المحاولة المخصصة لاسترداد نتائج المعاملة، باستخدام pollingInterval
و maxWaitingTime
و disableBackButton
.
pollingInterval
و maxWaitingTime
بالمللي ثانية، مع قيم افتراضية تبلغ 2000 مللي ثانية و60000 مللي ثانية، على التوالي. يؤدي ضبط disableBackButton
على القيمة true إلى تعطيل زر الرجوع أثناء إعادة المحاولة.maxWaitingTime
دون أي نتيجة، تقوم SDK بإرجاع SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS
. سيؤدي الضغط على زر الرجوع (إذا كان ممكّنًا) أثناء إعادة المحاولة إلى ظهور هذا الخطأ أيضًا.pollingInterval
maxWaitingTime
، فسيتم ضبط maxWaitingTime
تلقائيًا للمطابقة. القيم السالبة لأي معلمة افتراضية هي 0.configureRetryPolicy()
، فستقوم SDK افتراضيًا بإرجاع SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED
. عند استخدام الدفع SumUp كما هو موضح أدناه:
SumupPayment . builder ()
...
. foreignTransactionId ( UUID . randomUUID (). toString ())
. configureRetryPolicy ( 2000 , 60000 , true )
. build ();
إذا كانت هناك مشكلات في الاتصال ولا يمكن استرداد حالة المعاملة، فسوف تقوم واجهة برمجة التطبيقات بإرجاع ERROR_UNKNOWN_TRANSACTION_STATUS
. في مثل هذه الحالات، يمكنك الاستعلام عن حالة المعاملة عن طريق استدعاء واجهة برمجة تطبيقات حالة المعاملة SumUp باستخدام foreignTransactionId
المحدد.
سيتم ربط معرف foreignTransactionID
بالمعاملة ويمكن استخدامه لاسترداد التفاصيل المتعلقة بالمعاملة. راجع وثائق API للحصول على التفاصيل. يرجى التأكد من أن هذا المعرف فريد ضمن نطاق حساب التاجر SumUp والحسابات الفرعية. ويجب ألا يزيد طوله عن 128 حرفًا. يتوفر ExternalTransactionID عندما يتم استدعاء نشاط رد الاتصال: SumUpAPI.Param.FOREIGN_TRANSACTION_ID
لتخطي شاشة النجاح التي تظهر في نهاية المعاملة الناجحة، يمكن استخدام المعلمة skipSuccessScreen
. عند استخدام هذه المعلمة، يكون تطبيقك مسؤولاً عن عرض نتيجة المعاملة للعميل. بالاشتراك مع Receipts API، يمكن لتطبيقك أيضًا إرسال إيصالاتك الخاصة، راجع وثائق API للحصول على التفاصيل. يرجى ملاحظة أن شاشات النجاح ستستمر في الظهور عند استخدام قارئات SumUp Air Lite.
لتخطي الشاشة الفاشلة التي تظهر في نهاية المعاملة الفاشلة، يمكن استخدام المعلمة skipFailedScreen
. عند استخدام هذه المعلمة، يكون تطبيقك مسؤولاً عن عرض نتيجة المعاملة للعميل. يرجى ملاحظة أن الشاشات الفاشلة ستستمر في الظهور عند استخدام قارئات SumUp Air Lite.
لمصادقة حساب دون قيام المستخدم بكتابة بيانات اعتماد SumUp الخاصة به في كل مرة، يمكنك إنشاء رمز وصول باستخدام OAuth2.0 واستخدامه لتسجيل الدخول بشفافية إلى SumUp SDK.
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). accessToken ( "MY_ACCESS_TOKEN" ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );
للحصول على معلومات حول كيفية الحصول على الرمز المميز، يرجى الاطلاع على وثائق API.
إذا كان الرمز المميز غير صالح، فسيتم إرجاع SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN
.
إذا تم تسجيل الدخول حاليًا إلى حساب تاجر، فمن الممكن استرداد البيانات الخاصة بهذا الحساب.
if (! SumUpAPI . isLoggedIn ()) {
// no merchant account currently logged in
} else {
Merchant currentMerchant = SumUpAPI . getCurrentMerchant ();
}
SumUpAPI . logout ();
buildTypes {
release {
// All ProGuard rules required by the SumUp SDK are packaged with the library
minifyEnabled true
proguardFiles getDefaultProguardFile( ' proguard-android.txt ' )
}
}
يدعم SDK خدمات الموقع من Google، لتحسين دقة الموقع وتقليل استهلاك الطاقة.
من أجل استخدامه تحتاج إلى إضافة التبعية في ملف build.gradle
implementation " com.google.android.gms:play-services-location:19.0.1 "
إذا لم تتم إضافة تبعية GLS إلى المشروع أو لم يتم تثبيت خدمات Google Play على الجهاز المحمول، فستحدد SumUp SDK الموقع باستخدام خدمة الموقع الافتراضية التي يوفرها Android.
ملاحظة: يوصى باستخدام الإصدار 19.0.1 من GLS.
يتم التعامل مع الوظائف التالية بواسطة SumUp APIs:
SumUp Android SDK Changelog
ترخيص SumUp Android SDK