sumup android sdk
Release 5.0.3
Ce référentiel fournit une documentation étape par étape pour le SDK Android natif de SumUp, qui vous permet d'intégrer notre (nos) terminal(s) de carte propriétaire et sa plateforme de paiement pour accepter les paiements par carte de crédit et de débit (y compris VISA, MasterCard, American Express et plus). Le SDK communique de manière transparente avec le(s) terminal(s) de carte via Bluetooth (BLE 4.0). Lors du lancement d'un paiement, le SDK guide votre utilisateur à l'aide des écrans appropriés à travers chaque étape du processus de paiement. Dans le cadre du processus, SumUp fournit également l'écran de configuration du terminal de carte, ainsi que l'écran de vérification de la signature du titulaire de la carte. Le résultat du paiement est renvoyé avec les données pertinentes pour vos dossiers.
Aucune donnée de carte sensible n'est jamais transmise ou stockée sur le téléphone du commerçant. Toutes les données sont cryptées par le terminal de carte, qui a été entièrement certifié selon les normes les plus élevées de l'industrie (PCI, EMV I & II, Visa, MasterCard & Amex).
Pour plus d'informations sur les produits pour développeurs SumUp, veuillez consulter notre documentation sur l'API SumUp.
minSdkVersion 26 ou ultérieuretargetSDK 31 ou version ultérieureAjoutez le référentiel à vos dépendances Gradle :
allprojects {
repositories {
maven { url ' https://maven.sumup.com/releases ' }
}
}Ajoutez la dépendance à un module :
implementation ' com.sumup:merchant-sdk:5.0.3 'Initialisez les composants SumUp dans votre application :
public class SampleApplication extends Application {
@ Override
public void onCreate () {
super . onCreate ();
SumUpState . init ( this );
}
}Avant d'appeler les fonctionnalités du SDK SumUp, un compte marchand SumUp enregistré doit être connecté. Veuillez vous rendre sur https://me.sumup.com/developers pour récupérer votre clé d'affiliation en saisissant l'ID d'application de votre application. (par exemple com.sumup.sdksampleapp)
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );Remarque : Il est également possible de se connecter à un compte avec un jeton, sans que l'utilisateur ne saisisse ses identifiants de connexion SumUp dans le SDK. Veuillez vous référer à la section Authentification transparente
Une fois connecté, vous pouvez commencer à utiliser le SDK SumUp pour accepter les paiements par carte. Si aucun compte n'est connecté, SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN sera renvoyé.
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
}
}Plusieurs champs de réponse sont disponibles lorsque l'activité de rappel est appelée :
Les indicateurs de réponse sont fournis dans le Bundle qui est renvoyé à l'activité de rappel :
int resultCode = getIntent (). getExtras (). getInt ( SumUpAPI . Response . RESULT_CODE );Lorsqu'un commerçant est connecté, vous pouvez ouvrir cette activité pour accéder à tous les paramètres et options liés au lecteur de carte.
SumUpAPI . openCardReaderPage ( MainActivity . this , 4 ); prepareForCheckout() offre la possibilité de connecter le lecteur de carte avant de lancer le paiement, ce qui accélère le temps global de paiement.
Pour appeler cette méthode, l'utilisateur doit être connecté avec un compte SumUp et son lecteur de carte doit déjà être configuré. Ensuite, appelez prepareForCheckout() avant de lancer une extraction.
Remarque : les lecteurs de cartes Air et Solo restent connectés via BLE après chaque transaction, tandis que
prepareForCheckout()est utilisé lorsque le lecteur de carte est déconnecté (par exemple, le lecteur est hors de portée, l'application hôte perd le focus ou le lecteur est éteint).
Lors de la configuration de l'objet SumUpPayment , les paramètres facultatifs suivants peuvent être inclus :
Un montant de pourboire peut être traité en plus du total à l’aide du paramètre tip . Le montant du pourboire sera ensuite affiché lors du processus de paiement et inclus dans la réponse. Veuillez noter que le montant du pourboire ne peut pas être modifié pendant/après le paiement.
Cela permet au client d'ajouter un pourboire directement sur le lecteur de carte, plutôt que de demander le montant du pourboire sur l'appareil Android.
Un montant de pourboire peut être demandé directement dans le lecteur de carte à l'aide du paramètre tipOnCardReader , si le lecteur de carte prend en charge les pourboires. Voir exemple ici pour le champ tipOnCardReader .
Remarque : Tous les lecteurs de cartes ne prennent pas en charge cette fonctionnalité. Pour savoir si la fonctionnalité est prise en charge pour le dernier lecteur de carte enregistré, vous devez toujours vérifier
SumUpApi.isTipOnCardReaderAvailable(). Vous devez gérer ce cas vous-même afin d'éviter qu'aucun pourboire ne vous soit demandé. Veuillez également noter que sitipettipOnCardReadersont appelés, seul le montanttipOnCardReadersera pris en compte lors du paiement, s'il est disponible.
La fonctionnalité configureRetryPolicy() vous permet de définir des paramètres de nouvelle tentative personnalisés pour la récupération des résultats de transaction, à l'aide de pollingInterval , maxWaitingTime et disableBackButton .
pollingInterval et maxWaitingTime doivent être fournis en millisecondes, avec des valeurs par défaut de 2 000 ms et 60 000 ms, respectivement. La définition disableBackButton sur true désactive le bouton de retour lors des tentatives.maxWaitingTime s'écoule sans résultat, le SDK renvoie SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS . Appuyer sur le bouton de retour (si activé) pendant les tentatives déclenchera également cette erreur.pollingInterval dépasse maxWaitingTime , maxWaitingTime sera automatiquement ajusté en conséquence. Les valeurs négatives pour l’un ou l’autre paramètre sont par défaut 0.configureRetryPolicy() n'est pas utilisé, le SDK renvoie par défaut SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED . Lorsque vous utilisez le paiement SumUp comme indiqué ci-dessous :
SumupPayment . builder ()
...
. foreignTransactionId ( UUID . randomUUID (). toString ())
. configureRetryPolicy ( 2000 , 60000 , true )
. build (); S'il y a des problèmes de connectivité et que l'état de la transaction ne peut pas être récupéré, l'API renverra ERROR_UNKNOWN_TRANSACTION_STATUS . Dans de tels cas, vous pouvez interroger l'état de la transaction en appelant l'API d'état de la transaction SumUp à l'aide du foreignTransactionId spécifié.
L'identifiant foreignTransactionID sera associé à la transaction et pourra être utilisé pour récupérer les détails liés à la transaction. Consultez la documentation de l'API pour plus de détails. Veuillez vous assurer que cet identifiant est unique dans le cadre du compte marchand et des sous-comptes SumUp. Il ne doit pas dépasser 128 caractères. Le ForeignTransactionID est disponible lorsque l'activité de rappel est appelée : SumUpAPI.Param.FOREIGN_TRANSACTION_ID
Pour ignorer l'écran de réussite affiché à la fin d'une transaction réussie, le paramètre skipSuccessScreen peut être utilisé. Lorsque vous utilisez ce paramètre, votre application est chargée d'afficher le résultat de la transaction au client. En combinaison avec l'API Receipts, votre application peut également envoyer vos propres reçus. Consultez la documentation de l'API pour plus de détails. Veuillez noter que les écrans de réussite s'afficheront toujours lors de l'utilisation des lecteurs SumUp Air Lite.
Pour ignorer l'écran d'échec affiché à la fin d'une transaction ayant échoué, le paramètre skipFailedScreen peut être utilisé. Lorsque vous utilisez ce paramètre, votre application est chargée d'afficher le résultat de la transaction au client. Veuillez noter que les écrans défaillants s'afficheront toujours lors de l'utilisation des lecteurs SumUp Air Lite.
Pour authentifier un compte sans que l'utilisateur ne saisisse à chaque fois ses informations d'identification SumUp, vous pouvez générer un jeton d'accès à l'aide d'OAuth2.0 et l'utiliser pour vous connecter de manière transparente au SDK SumUp.
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). accessToken ( "MY_ACCESS_TOKEN" ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );Pour plus d'informations sur la façon d'obtenir un jeton, veuillez consulter la documentation de l'API.
Si le jeton n'est pas valide, SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN sera renvoyé.
Si un compte marchand est actuellement connecté, il est possible de récupérer les données de ce compte.
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 ' )
}
}Le SDK prend en charge les services de localisation Google, pour améliorer la précision de la localisation et réduire la consommation d'énergie.
Pour l'utiliser, vous devez ajouter la dépendance dans le fichier build.gradle
implementation " com.google.android.gms:play-services-location:19.0.1 "Si la dépendance GLS n'est pas ajoutée au projet ou si les services Google Play ne sont pas installés sur l'appareil mobile, le SDK SumUp déterminera l'emplacement avec le service de localisation par défaut fourni par Android.
REMARQUE : L'utilisation de GLS version 19.0.1 est recommandée.
Les fonctions suivantes sont gérées par les API SumUp :
Journal des modifications du SDK SumUp Android
Licence du SDK Android SumUp
