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商户账户。请前往https://me.sumup.com/developers输入您应用的应用ID来检索您的Affiliate Key。 （例如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 许可证
