sumup android sdk
Release 5.0.3
Dieses Repository bietet eine Schritt-für-Schritt-Dokumentation für das native Android SDK von SumUp, das Ihnen die Integration unserer proprietären Kartenterminals und seiner Zahlungsplattform ermöglicht, um Kredit- und Debitkartenzahlungen (einschließlich VISA, MasterCard, American Express und mehr) zu akzeptieren. Das SDK kommuniziert transparent über Bluetooth (BLE 4.0) mit dem/den Kartenterminal(s). Beim Einleiten eines Bezahlvorgangs führt das SDK Ihren Benutzer mithilfe geeigneter Bildschirme durch jeden Schritt des Zahlungsprozesses. Als Teil des Prozesses stellt SumUp auch den Bildschirm zur Einrichtung des Kartenterminals sowie den Bildschirm zur Überprüfung der Unterschrift des Karteninhabers bereit. Das Checkout-Ergebnis wird mit den relevanten Daten für Ihre Unterlagen zurückgegeben.
Es werden niemals sensible Kartendaten an das Telefon des Händlers weitergeleitet oder dort gespeichert. Alle Daten werden vom Kartenterminal verschlüsselt, das vollständig nach den höchsten Industriestandards (PCI, EMV I & II, Visa, MasterCard & Amex) zertifiziert wurde.
Weitere Informationen zu SumUp-Entwicklerprodukten finden Sie in unserer SumUp-API-Dokumentation.
minSdkVersion 26 oder höher erforderlichtargetSDK 31 oder höherFügen Sie das Repository zu Ihren Gradle-Abhängigkeiten hinzu:
allprojects {
repositories {
maven { url ' https://maven.sumup.com/releases ' }
}
}Fügen Sie die Abhängigkeit zu einem Modul hinzu:
implementation ' com.sumup:merchant-sdk:5.0.3 'Initialisieren Sie die SumUp-Komponenten in Ihrer App:
public class SampleApplication extends Application {
@ Override
public void onCreate () {
super . onCreate ();
SumUpState . init ( this );
}
}Bevor Sie Funktionen des SumUp SDK aufrufen können, müssen Sie sich bei einem registrierten SumUp-Händlerkonto anmelden. Bitte gehen Sie zu https://me.sumup.com/developers, um Ihren Affiliate-Schlüssel abzurufen, indem Sie die Anwendungs-ID Ihrer App eingeben. (z. B. com.sumup.sdksampleapp)
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );Hinweis: Es ist auch möglich, sich mit einem Token bei einem Konto anzumelden, ohne dass der Benutzer seine SumUp-Anmeldeinformationen im SDK eingeben muss. Weitere Informationen finden Sie im Abschnitt „Transparente Authentifizierung“.
Sobald Sie angemeldet sind, können Sie das SumUp SDK verwenden, um Kartenzahlungen zu akzeptieren. Wenn kein Konto angemeldet ist, wird SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN zurückgegeben.
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
}
}Beim Aufruf der Callback-Aktivität stehen mehrere Antwortfelder zur Verfügung:
Die Antwortflags werden im Bundle bereitgestellt, das an die Rückrufaktivität zurückgegeben wird:
int resultCode = getIntent (). getExtras (). getInt ( SumUpAPI . Response . RESULT_CODE );Wenn ein Händler angemeldet ist, können Sie diese Aktivität öffnen, um auf alle Einstellungen und Optionen im Zusammenhang mit dem Kartenlesegerät zuzugreifen.
SumUpAPI . openCardReaderPage ( MainActivity . this , 4 ); prepareForCheckout() bietet die Möglichkeit, den Kartenleser vor dem Einleiten des Checkouts anzuschließen, was die gesamte Checkout-Zeit beschleunigt.
Um diese Methode aufzurufen, muss der Benutzer mit einem SumUp-Konto angemeldet sein und sein Kartenleser sollte bereits eingerichtet sein. Rufen Sie als Nächstes prepareForCheckout() auf, bevor Sie einen Checkout einleiten.
Hinweis: Air- und Solo-Kartenleser bleiben nach jeder Transaktion über BLE verbunden, während
prepareForCheckout()verwendet wird, wenn die Verbindung zum Kartenleser getrennt wird (z. B. befindet sich der Leser außerhalb der Reichweite, die Host-App verliert den Fokus oder der Leser wird ausgeschaltet).
Beim Einrichten des SumUpPayment Objekts können die folgenden optionalen Parameter einbezogen werden:
Über den tip kann zusätzlich zum total ein Trinkgeldbetrag verarbeitet werden. Der Trinkgeldbetrag wird dann beim Bezahlvorgang angezeigt und in die Antwort mit einbezogen. Bitte beachten Sie, dass der Trinkgeldbetrag während/nach dem Check-out nicht geändert werden kann.
Dadurch kann der Kunde direkt am Kartenlesegerät Trinkgeld hinzufügen, anstatt auf dem Android-Gerät zur Eingabe eines Trinkgeldbetrags aufzufordern.
Ein Trinkgeldbetrag kann mithilfe des Parameters tipOnCardReader direkt im Kartenleser abgefragt werden, wenn der Kartenleser Trinkgeld unterstützt. Siehe hier Beispiel für das Feld tipOnCardReader .
Hinweis: Nicht alle Kartenleser unterstützen diese Funktion. Um herauszufinden, ob die Funktion für den zuletzt gespeicherten Kartenleser unterstützt wird, sollten Sie immer
SumUpApi.isTipOnCardReaderAvailable()überprüfen. Sie müssen diesen Fall selbst bearbeiten, um zu vermeiden, dass kein Trinkgeld verlangt wird. Bitte beachten Sie auch, dass beim Aufruf vontipundtipOnCardReadernurtipOnCardReader-Betrag beim Bezahlvorgang berücksichtigt wird, sofern verfügbar.
Mit der Funktion configureRetryPolicy() können Sie benutzerdefinierte Wiederholungsparameter für den Abruf von Transaktionsergebnissen festlegen, indem Sie pollingInterval , maxWaitingTime und disableBackButton verwenden.
pollingInterval als auch maxWaitingTime sollten in Millisekunden angegeben werden, mit Standardwerten von 2000 ms bzw. 60000 ms. Wenn Sie disableBackButton auf „true“ setzen, wird die Zurück-Schaltfläche bei Wiederholungsversuchen deaktiviert.maxWaitingTime ohne Ergebnis verstreicht, gibt das SDK SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS zurück. Auch das Drücken der Zurück-Taste (falls aktiviert) während der Wiederholungsversuche löst diesen Fehler aus.pollingInterval maxWaitingTime überschreitet, wird maxWaitingTime automatisch entsprechend angepasst. Negative Werte für jeden Parameter sind standardmäßig 0.configureRetryPolicy() nicht verwendet wird, gibt das SDK standardmäßig SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED zurück. Bei Nutzung der SumUp-Zahlung wie unten dargestellt:
SumupPayment . builder ()
...
. foreignTransactionId ( UUID . randomUUID (). toString ())
. configureRetryPolicy ( 2000 , 60000 , true )
. build (); Wenn Verbindungsprobleme vorliegen und der Transaktionsstatus nicht abgerufen werden kann, gibt die API ERROR_UNKNOWN_TRANSACTION_STATUS zurück. In solchen Fällen können Sie den Transaktionsstatus abfragen, indem Sie die SumUp-Transaktionsstatus-API mit der angegebenen foreignTransactionId aufrufen.
Die foreignTransactionID -Kennung wird mit der Transaktion verknüpft und kann zum Abrufen von Details im Zusammenhang mit der Transaktion verwendet werden. Weitere Informationen finden Sie in der API-Dokumentation. Bitte stellen Sie sicher, dass diese ID im Rahmen des SumUp-Händlerkontos und der Unterkonten eindeutig ist. Es darf nicht länger als 128 Zeichen sein. Die ForeignTransactionID ist verfügbar, wenn die Rückrufaktivität aufgerufen wird: SumUpAPI.Param.FOREIGN_TRANSACTION_ID
Um den am Ende einer erfolgreichen Transaktion angezeigten Erfolgsbildschirm zu überspringen, kann der Parameter skipSuccessScreen verwendet werden. Bei Verwendung dieses Parameters ist Ihre Anwendung dafür verantwortlich, dem Kunden das Transaktionsergebnis anzuzeigen. In Kombination mit der Receipts-API kann Ihre Anwendung auch Ihre eigenen Quittungen senden. Weitere Informationen finden Sie in der API-Dokumentation. Bitte beachten Sie, dass bei Verwendung der SumUp Air Lite-Lesegeräte weiterhin Erfolgsbildschirme angezeigt werden.
Um den am Ende einer fehlgeschlagenen Transaktion angezeigten Fehlerbildschirm zu überspringen, kann der Parameter skipFailedScreen verwendet werden. Bei Verwendung dieses Parameters ist Ihre Anwendung dafür verantwortlich, dem Kunden das Transaktionsergebnis anzuzeigen. Bitte beachten Sie, dass bei Verwendung der SumUp Air Lite-Lesegeräte weiterhin fehlerhafte Bildschirme angezeigt werden.
Um ein Konto zu authentifizieren, ohne dass der Benutzer jedes Mal seine SumUp-Anmeldeinformationen eingeben muss, können Sie mit OAuth2.0 ein Zugriffstoken generieren und es für die transparente Anmeldung beim SumUp SDK verwenden.
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). accessToken ( "MY_ACCESS_TOKEN" ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );Informationen zum Erhalten eines Tokens finden Sie in der API-Dokumentation.
Wenn das Token ungültig ist, wird SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN zurückgegeben.
Wenn aktuell ein Händlerkonto angemeldet ist, besteht die Möglichkeit, die Daten für dieses Konto abzurufen.
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 ' )
}
}Das SDK unterstützt Google Location Services, um die Standortgenauigkeit zu verbessern und den Stromverbrauch zu senken.
Um es verwenden zu können, müssen Sie die Abhängigkeit in der Datei build.gradle hinzufügen
implementation " com.google.android.gms:play-services-location:19.0.1 "Wenn die GLS-Abhängigkeit nicht zum Projekt hinzugefügt wird oder die Google Play-Dienste nicht auf dem Mobilgerät installiert sind, ermittelt das SumUp SDK den Standort mit dem von Android bereitgestellten Standard-Standortdienst.
HINWEIS: Die Verwendung der GLS-Version 19.0.1 wird empfohlen.
Die folgenden Funktionen werden von den SumUp-APIs übernommen:
SumUp Android SDK-Änderungsprotokoll
SumUp Android SDK-Lizenz
