sumup android sdk
Release 5.0.3
Este repositório fornece uma documentação passo a passo para o SDK Android nativo da SumUp, que permite integrar nossos terminais de cartão proprietários e sua plataforma de pagamento para aceitar pagamentos com cartão de crédito e débito (incluindo VISA, MasterCard, American Express e mais). O SDK se comunica de forma transparente com os terminais do cartão via Bluetooth (BLE 4.0). Ao iniciar uma finalização de compra, o SDK orienta seu usuário usando telas apropriadas em cada etapa do processo de pagamento. Como parte do processo, a SumUp disponibiliza também a tela de configuração do terminal do cartão, juntamente com a tela de verificação da assinatura do titular do cartão. O resultado do checkout é retornado com os dados relevantes para seus registros.
Nenhum dado confidencial do cartão é transmitido ou armazenado no telefone do comerciante. Todos os dados são criptografados pelo terminal de cartão, que foi totalmente certificado de acordo com os mais altos padrões da indústria (PCI, EMV I e II, Visa, MasterCard e Amex).
Para obter mais informações sobre os produtos para desenvolvedores SumUp, consulte nossa documentação da API SumUp.
minSdkVersion 26 ou posteriortargetSDK 31 ou posteriorAdicione o repositório às suas dependências do Gradle:
allprojects {
repositories {
maven { url ' https://maven.sumup.com/releases ' }
}
}Adicione a dependência a um módulo:
implementation ' com.sumup:merchant-sdk:5.0.3 'Inicialize os componentes SumUp no seu aplicativo:
public class SampleApplication extends Application {
@ Override
public void onCreate () {
super . onCreate ();
SumUpState . init ( this );
}
}Antes de acessar qualquer recurso do SumUp SDK, uma conta de comerciante SumUp registrada precisa estar logada. Acesse https://me.sumup.com/developers para recuperar sua Chave de Afiliado inserindo o ID do seu aplicativo. (por exemplo, com.sumup.sdksampleapp)
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );Nota: Também é possível iniciar sessão numa conta com um token, sem que o utilizador introduza as suas credenciais de início de sessão SumUp no SDK. Consulte a seção Autenticação Transparente
Uma vez logado, você pode começar a usar o SumUp SDK para aceitar pagamentos com cartão. Se nenhuma conta estiver logada, SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN será retornado.
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
}
}Vários campos de resposta estão disponíveis quando a atividade de retorno de chamada é chamada:
Os sinalizadores de resposta são fornecidos no Bundle que é passado de volta para a atividade de retorno de chamada:
int resultCode = getIntent (). getExtras (). getInt ( SumUpAPI . Response . RESULT_CODE );Quando um estabelecimento comercial estiver logado, você poderá abrir esta atividade para acessar todas as configurações e opções relacionadas ao leitor de cartão.
SumUpAPI . openCardReaderPage ( MainActivity . this , 4 ); prepareForCheckout() oferece a possibilidade de conectar o leitor de cartão antes de iniciar o checkout, o que acelera o tempo geral de checkout.
Para chamar este método, o usuário precisa estar logado com uma conta SumUp e seu leitor de cartão já deve estar configurado. Em seguida, chame prepareForCheckout() antes de iniciar uma finalização da compra.
Nota: Os leitores de cartão Air e Solo permanecem conectados via BLE após cada transação, enquanto
prepareForCheckout()é usado quando o leitor de cartão é desconectado (por exemplo, o leitor está fora do alcance, o aplicativo host perde o foco ou o leitor é desligado).
Ao configurar o objeto SumUpPayment , os seguintes parâmetros opcionais podem ser incluídos:
Um valor de gorjeta pode ser processado além do total usando o parâmetro tip . O valor da gorjeta será mostrado durante o processo de finalização da compra e incluído na resposta. Observe que o valor da gorjeta não pode ser alterado durante/após a finalização da compra.
Isso permite que o cliente adicione uma gorjeta diretamente no leitor de cartão, em vez de solicitar o valor da gorjeta no dispositivo Android.
Um valor de gorjeta pode ser solicitado diretamente no leitor de cartão usando o parâmetro tipOnCardReader , se o leitor de cartão suportar gorjetas. Veja aqui o exemplo do campo tipOnCardReader .
Nota: Nem todos os leitores de cartão oferecem suporte a esse recurso. Para descobrir se o recurso é compatível com o último leitor de cartão salvo, você deve sempre verificar
SumUpApi.isTipOnCardReaderAvailable(). Você deve cuidar deste caso sozinho para evitar que nenhuma dica seja solicitada. Observe também que setipetipOnCardReaderforem chamados, apenas o valortipOnCardReaderserá considerado durante a finalização da compra, se disponível.
O recurso configureRetryPolicy() permite definir parâmetros de nova tentativa personalizados para recuperação de resultados de transações, usando pollingInterval , maxWaitingTime e disableBackButton .
pollingInterval e maxWaitingTime devem ser fornecidos em milissegundos, com valores padrão de 2.000 ms e 60.000 ms, respectivamente. Definir disableBackButton como true desativa o botão Voltar durante novas tentativas.maxWaitingTime expirar sem resultado, o SDK retornará SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS . Pressionar o botão Voltar (se habilitado) durante novas tentativas também acionará esse erro.pollingInterval exceder maxWaitingTime , maxWaitingTime será automaticamente ajustado para corresponder. Os valores negativos para qualquer parâmetro são padronizados como 0.configureRetryPolicy() não for usado, o padrão do SDK será retornar SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED . Ao utilizar o pagamento SumUp conforme mostrado abaixo:
SumupPayment . builder ()
...
. foreignTransactionId ( UUID . randomUUID (). toString ())
. configureRetryPolicy ( 2000 , 60000 , true )
. build (); Se houver problemas de conectividade e o status da transação não puder ser recuperado, a API retornará ERROR_UNKNOWN_TRANSACTION_STATUS . Nesses casos, você pode consultar o status da transação chamando a API de status da transação SumUp usando o foreignTransactionId especificado.
O identificador foreignTransactionID será associado à transação e pode ser usado para recuperar detalhes relacionados à transação. Consulte a documentação da API para obter detalhes. Certifique-se de que este ID é único no âmbito da conta e subcontas de comerciante SumUp. Não deve ter mais de 128 caracteres. O ForeignTransactionID está disponível quando a atividade de retorno de chamada é chamada: SumUpAPI.Param.FOREIGN_TRANSACTION_ID
Para pular a tela de sucesso mostrada ao final de uma transação bem-sucedida, o parâmetro skipSuccessScreen pode ser usado. Ao utilizar este parâmetro sua aplicação é responsável por exibir o resultado da transação ao cliente. Em combinação com a API Receipts, seu aplicativo também pode enviar seus próprios recibos. Consulte a documentação da API para obter detalhes. Observe que as telas de sucesso ainda serão mostradas ao usar os leitores SumUp Air Lite.
Para pular a tela de falha mostrada no final de uma transação com falha, o parâmetro skipFailedScreen pode ser usado. Ao utilizar este parâmetro sua aplicação é responsável por exibir o resultado da transação ao cliente. Observe que as telas com falha ainda serão exibidas ao usar os leitores SumUp Air Lite.
Para autenticar uma conta sem que o usuário digite suas credenciais SumUp todas as vezes, você pode gerar um token de acesso usando OAuth2.0 e usá-lo para fazer login de forma transparente no SumUp SDK.
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). accessToken ( "MY_ACCESS_TOKEN" ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );Para obter informações sobre como obter um token, consulte a documentação da API.
Se o token for inválido, SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN será retornado.
Se uma conta de comerciante estiver logada, é possível recuperar os dados desta conta.
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 ' )
}
}O SDK oferece suporte aos Serviços de localização do Google para melhorar a precisão da localização e reduzir o consumo de energia.
Para usá-lo você precisa adicionar a dependência no arquivo build.gradle
implementation " com.google.android.gms:play-services-location:19.0.1 "Se a dependência GLS não for adicionada ao projeto ou o Google Play Services não estiver instalado no dispositivo móvel, o SumUp SDK determinará a localização com o Serviço de Localização padrão fornecido pelo Android.
NOTA: Recomenda-se usar o GLS versão 19.0.1.
As seguintes funções são gerenciadas pelas APIs SumUp:
Log de alterações do SumUp Android SDK
Licença SumUp Android SDK
