sumup android sdk
Release 5.0.3
此儲存庫提供了 SumUp 原生 Android SDK 的分步文檔，使您能夠整合我們的專有卡終端機及其支付平台以接受信用卡和金融卡付款（包括 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商家帳戶。 （例如com.sumup.sdksampleapp）
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );注意：也可以使用令牌登入帳戶，而無需使用者在 SDK 中輸入其 SumUp 登入憑證。請參閱透明身份驗證部分
登入後，您可以開始使用 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
}
}呼叫回調活動時，有幾個回應欄位可用：
響應標誌在傳回回調活動的 Bundle 中提供：
int resultCode = getIntent (). getExtras (). getInt ( SumUpAPI . Response . RESULT_CODE );當商家登入後，您可以開啟此活動以存取與讀卡機相關的所有設定和選項。
SumUpAPI . openCardReaderPage ( MainActivity . this , 4 );prepareForCheckout()提供了在開始結帳之前連接讀卡機的可能性，從而加快了整體結帳時間。
要呼叫此方法，用戶需要使用 SumUp 帳戶登錄，並且他們的讀卡機應該已經設定。接下來，在開始結帳之前呼叫prepareForCheckout() 。
注意：Air 和 Solo 讀卡機在每次交易後透過 BLE 保持連接，而當讀卡機斷開連接時（例如，讀卡機超出範圍、主機應用程式失去焦點或讀卡機關閉），則使用
prepareForCheckout()。
設定SumUpPayment物件時，可以包含以下可選參數：
除了使用tip參數處理total之外，還可以處理小費金額。小費金額將在結帳過程中顯示並包含在回覆中。請注意，結帳期間/結帳後無法更改小費金額。
這允許客戶直接在讀卡機上添加小費，而不是在 Android 裝置上提示輸入小費金額。
如果讀卡機支援小費，則可以使用tipOnCardReader參數直接在讀卡機中提示小費金額。請參閱此處欄位tipOnCardReader的範例。
注意：並非所有讀卡機都支援此功能。若要了解上次儲存的讀卡機是否支援該功能，您應該始終檢查
SumUpApi.isTipOnCardReaderAvailable()。您必須自行處理這種情況，以免提示不提示。另請注意，如果同時呼叫tip和tipOnCardReader，則結帳時僅考慮tipOnCardReader金額（如果有）。
configureRetryPolicy()功能可讓您使用pollingInterval 、 maxWaitingTime和disableBackButton設定用於交易結果擷取的自訂重試參數。
pollingInterval和maxWaitingTime均應以毫秒為單位提供，預設值分別為 2000 ms 和 60000 ms。將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 ();如果有連線問題且無法擷取交易狀態，API 將傳回ERROR_UNKNOWN_TRANSACTION_STATUS 。此時，您可以使用指定的foreignTransactionId來呼叫SumUp交易狀態介面查詢交易狀態。
foreignTransactionID識別碼將與交易相關聯，並可用於檢索與交易相關的詳細資訊。詳細資訊請參閱 API 文件。請確保該ID在SumUp商家帳戶及子帳戶範圍內唯一。它不得超過 128 個字元。呼叫回呼活動時，foreignTransactionID 可用： SumUpAPI.Param.FOREIGN_TRANSACTION_ID
若要跳過成功交易結束時顯示的成功畫面，可以使用skipSuccessScreen參數。使用此參數時，您的應用程式負責向客戶顯示交易結果。與收據 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 );關於如何取得token，請參閱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 提供的預設位置服務來確定位置。
注意：建議使用 GLS 版本 19.0.1。
以下函數由 SumUp API 處理：
SumUp Android SDK 變更日誌
SumUp Android SDK 許可證
