Erste Schritte mit Android SDK

Eigenschaften

Mit dem Trust Payments Android SDK können Sie eine vorgefertigte oder benutzerdefinierte Benutzeroberfläche nahtlos in Ihre Anwendung integrieren, um Kartenzahlungen zu akzeptieren und das Starke Kundenauthentifizierung (SCA) Mandat zu erfüllen.

Verwenden Sie diese Integration, wenn Sie eine vorgefertigte "Drop-In"-UI benötigen, die die folgenden Funktionen unterstützt:

• Kartenzahlungen
• Tokenisierung Zahlungen
• Anpassung der UI-Komponenten an das Branding Ihres Unternehmens
• Gebietsschema und benutzerdefinierte Übersetzungen

Wenn Sie bereits Ihre eigenen Kassenansichten in Ihrer Android App erstellt haben, aber eine Methode zur Verarbeitung von Zahlungen an das Trust Payments Gateway benötigen, können Sie unsere Zahlungsverkehrsmanager API verwenden.

  Klicken Sie hier, um mehr zu erfahren.

1. Installieren Sie das SDK in Ihrer Anwendung

Um das Mobile SDK in Ihr Projekt einzubinden, müssen Sie Gradleverwenden, ein Build-Automatisierungstool, das Funktionen zur Verwaltung von Abhängigkeiten bietet:

Integration von SDK-Artefakten als Abhängigkeit von Maven

Fügen Sie in Ihrer Build-Datei auf Anwendungsebene ( gradle ) die folgenden Abhängigkeiten hinzu:

// Trust Payments SDK core dependency
implementation 'com.trustpayments.mobile:core:<latest_version>'

// Optional UI module providing ready-to-use "drop-in" view
implementation 'com.trustpayments.mobile:ui:<latest_version>'

Um das Mobile SDK zu integrieren, fügen Sie die folgenden Abhängigkeiten zu Ihrer App-Level-Build-Datei hinzu.gradle :

Fügen Sie in Ihrer root-level build.gradle Datei die folgende Abhängigkeit hinzu, um das Cardinal SDK zu erhalten.

allprojects {
  repositories {
    google()
    ...
    maven {
      url "https://gitlab.com/api/v4/projects/56100229/packages/maven"
      name "GitLab"
      credentials(HttpHeaderCredentials) {
        name = "Private-Token"
        value = <gitlab_token>
      }
      authentication {
        header(HttpHeaderAuthentication)
      }
    }
  }
}

Integration des SDK in Ihr Projekt unter Verwendung des Quellcodes

Wenn Sie den Quellcode des SDK in Ihr Projekt integrieren möchten, schließen Sie bitte sowohl das Core- als auch das UI-Modul ein.

// Trust Payments SDK core dependency
implementation project(":core")

// Optional UI module providing ready-to-use "drop-in" view
implementation project(":ui")

Fügen Sie in Ihrer root-level build.gradle Datei die folgende Abhängigkeit hinzu, um das Cardinal SDK zu erhalten.

allprojects {
  repositories {
    google()
    ...
    maven {
      url "https://gitlab.com/api/v4/projects/56100229/packages/maven"
      name "GitLab"
      credentials(HttpHeaderCredentials) {
        name = "Private-Token"
        value = <gitlab_token>
      }
      authentication {
        header(HttpHeaderAuthentication)
      }
    }
  }
}

2. Initialisieren Sie das Android SDK in Ihrer Anwendung

Konfigurieren Sie die Instanz

Bevor Sie eine Zahlungsanforderung ausführen können, muss eine Instanz von PaymentTransactionManager benötigt wird. Um sie zu instanziieren, müssen Sie den Anwendungskontext angeben und den Benutzernamen und das Gateway festlegen. Außerdem müssen Sie einen Wert für isCardinalLive Flagge (wenn sie auf true gesetzt ist, werden alle 3-D Secure-bezogenen Operationen auf die 3-D Secure Live-Umgebung ausgerichtet, andernfalls wird die Staging-Umgebung verwendet). Der Parameter, cardinalStyleManagerist optional und ermöglicht die Einrichtung von UI-Anpassungen für 3-D Secure Ansichten. isLocationDataConsentGiven Parameter zeigt dem SDK an, ob Ihre App die Zustimmung des Kunden zur Erfassung seines Gerätestandorts als Teil Ihrer App-Datenschutzrichtlinie erhalten hat. Bitte finden Sie ein Beispiel PaymentTransactionManager Verwendung des Konstruktors unten:

PaymentTransactionManager(
  context = applicationContext,
  gatewayType = TrustPaymentsGatewayType.EU,
  isCardinalLive = false,
  merchantUsername = usernameFromTrustPayments,
  cardinalStyleManager = null,
  isLocationDataConsentGiven = false
)

Mit der Version 2.7.10.1 des Android SDK haben wir einen zusätzlichen Parameter in die SDKs aufgenommen PaymentTransactionManager Klasse namens isLocationDataConsentGiven. Standardmäßig, isLocationDataConsentGiven auf "false" gesetzt ist, bedeutet dies, dass der Kunde Ihrer App-Datenschutzrichtlinie nicht zugestimmt hat, in der Sie um Zustimmung zur Erfassung der Gerätestandortdaten bitten. Die Informationen, die erforderlich sind, damit die Datenschutzrichtlinie dem Kunden angezeigt werden kann, finden Sie unter hier.

Um die Wahrscheinlichkeit zu verringern, dass Ihre Kunden vom Kartenaussteller zu einer weiteren Authentifizierung aufgefordert werden, sollten Sie folgende Punkte beachten:

1. Sobald Ihr Kunde Ihrer App-Datenschutzrichtlinie zugestimmt hat, die auch Standortdaten umfasst, muss die Zustimmung zu Ihrer App-Datenschutzrichtlinie an das Trust Payments SDK weitergegeben werden. PaymentTransactionManager Instanz durch Setzen von isLocationDataConsentGiven als wahr. 

2. Beantragen Sie, dass GPS aktiviert werden kann, wenn es derzeit vom Kunden der App deaktiviert wurde.
3. Erstellen Sie eine Eingabeaufforderung zur Standortzustimmung, wenn Ihre Anwendung eine Instanz der PaymentTransactionManager Klasse. Sie müssen die Berechtigungen in die Manifestdatei aufnehmen:
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Wenn der Kunde Ihrer App die Erlaubnis zum Zugriff auf den Gerätestandort erteilt hat, versucht das SDK, den Gerätestandort zu erfassen. Bewährte Verfahren zur Erstellung der Aufforderung zur Zustimmung zum Gerätestandort finden Sie in den offiziellen Best Practices von Google: https://support.google.com/googleplay/android-developer/answer/11150561

Ein Beispiel dafür, wie Sie die Datenschutzrichtlinien in Ihrer Anwendung zur Akzeptanz durch den Kunden präsentieren können, finden Sie in unserer Beispiel-Anwendungsklasse PrivacyPolicyActivity.kt

Aufblasen der Drop-In Payment View

Um unser Standardprogramm Drop-In Payment View aufzublasen, müssen Sie es zu einer entsprechenden XML-Datei hinzufügen:

<?xml version="1.0" encoding="utf-8"?>
<ScrollView xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:fillViewport="true">

<com.trustpayments.mobile.ui.dropin.DropInPaymentView
android:id="@+id/dropInPaymentView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:padding="20dp" />
</ScrollView>

Dann muss eine Aktivität, die mit diesem Layout verbunden ist, die erforderliche Hörerschnittstelle implementieren und ihre Methoden überschreiben, die für dieses Drop-In Payment View vorgesehen sind. Diese Methoden liefern alle notwendigen Daten für die korrekte Initialisierung der PaymentTransactonManager Instanz und verarbeiten eine Transaktion.

Beispiel:

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.trustpayments.mobile.ui.dropin.DropInPaymentView
import com.trustpayments.mobile.ui.model.PaymentInputType
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import androidx.lifecycle.lifecycleScope
import com.trustpayments.mobile.core.PaymentSession
import com.trustpayments.mobile.core.services.api.TrustPaymentsGatewayType
import com.trustpayments.mobile.core.services.transaction.PaymentTransactionManager

/**
 * SampleActivity demonstrates the implementation of a drop-in payment view 
 * for handling payment transactions.
 */
class SampleActivity : AppCompatActivity(R.layout.activity_sample),
    DropInPaymentView.DropInPaymentViewListener {

    // Payment transaction manager responsible for managing payment transactions
    private val paymentTransactionManager by lazy {
        PaymentTransactionManager(
            context = this,
            gatewayType = TrustPaymentsGatewayType.EU,
            isCardinalLive = false,
            merchantUsername = "usernameFromTrustpayments",
            cardinalStyleManager = null,
            isLocationDataConsentGiven = false
        )
    }
    
    // Payment session for managing the payment session lifecycle
    private lateinit var paymentSession: PaymentSession

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Set the drop-in payment view listener
        findViewById<DropInPaymentView>(R.id.dropInPaymentView).dropInPaymentViewListener=this
        // Create a payment session with JWT token obtained from the server
        paymentSession = paymentTransactionManager.createSession(getJWTToken())
    }
    
    /**
     * Get JWT token from the server.
     * @return JWT token string
     */
    private fun getJWTToken(): String {
        return ""
    }

    /**
     * Notify about changes in the payment form data (PAN, Expiry Date, CVV).
     * @param paymentInputType The type of payment input being updated
     * @param input The input value
     */
    override fun onInputValid(paymentInputType: PaymentInputType, input: String) {
        when (paymentInputType) {
            PaymentInputType.PAN -> paymentSession.cardPan = input
            PaymentInputType.ExpiryDate -> paymentSession.cardExpiryDate = input
            PaymentInputType.CVV -> paymentSession.cardSecurityCode = input
        }
    }

    /**
     * Notify about the Pay Button click event.
     * Executes the payment session in the background and processes the result.
     */
    override fun onPayButtonClicked() {
        lifecycleScope.launch {
            val result: PaymentTransactionManager.Response = withContext(Dispatchers.IO) {
                paymentTransactionManager.executeSession(paymentSession)
            }
            // Process the result
        }
    }
}

Zahlungsverkehrsmanager

Wenn Sie bereits eigene Kassenansichten in Ihrer Android App erstellt haben oder dies vorhaben, aber eine Methode zur Verarbeitung von Zahlungen an das Trust Payments Gateway benötigen, können Sie unsere Zahlungsverkehrsmanager API verwenden.

val paymentTransactionManager =
PaymentTransactionManager(
  context = applicationContext,
  gatewayType = TrustPaymentsGatewayType.EU,
  isCardinalLive = false,
  merchantUsername = usernameFromTrustpayments,
  cardinalStyleManager = null,
  isLocationDataConsentGiven = false
)

paymentTransactionManager.executeSession(paymentSession, activityProvider)

Beim Aufruf der paymentTransactionManager.executeSession Methode und auch die Angabe von THREEDQUERY im JWT payload requesttypedescriptions Feldliste, müssen Sie sicherstellen, dass Sie executeSession mit Parameter activityProvider. Die activityProvider ist ein Rückruf an eine Activity. Die Activity wäre das Fenster in Ihrer Android App und dieses muss unserem Payment SDK bekannt sein, um das 3-D Secure Version 2 native Challenge-Fenster für Ihre Kunden erfolgreich anzuzeigen.

In unserem Gitlab Repository haben wir verschiedene App-Beispiele und das folgende verlinkte Beispiel zeigt, wie Sie eine Kartenzahlung mit 3-D Secure konfigurieren würden. Klicken Sie hier, um das Beispiel in einer neuen Registerkarte zu öffnen.

3. Webhooks konfigurieren

Es wird dringend empfohlen, dass Sie Webhooks für Ihre Mobile SDK-Lösung konfigurieren. Wenn diese konfiguriert sind, wird URL-Benachrichtigungen an Ihr System gesendet, wenn Zahlungen auf Ihrem Konto verarbeitet werden.

1. Melden Sie sich auf Portal an.
   
   
2. Suchen Sie nach Ihrem sitereference über das Suchfeld oben auf der Seite.
   
   
3. Wenn Sie die Details Ihrer Website anzeigen, klicken Sie auf "Regel-Manager".
   
   
   
   
4. Wählen Sie die Aktionsart "URL-Benachrichtigung" aus der Dropdown-Liste und Ihr Browser wird umgeleitet.
   
   
   
   
5. Erstellen Sie eine neue Regel URL-Benachrichtigung :
   • (A) Klicken Sie auf "Add new condition" und geben an, unter welchen Umständen die URL-Benachrichtigung nach einer Transaktion ausgelöst werden soll. Vergewissern Sie sich, dass in dem angezeigten Feld Anforderungen das Kontrollkästchen "AUTH" aktiviert ist (d. h. die Meldung wird nach der Zahlung ausgelöst Genehmigungen).
     Klicken Sie hier, um mehr über die Konfiguration von Bedingungen zu erfahren.
   • (B) Klicken Sie auf "Add new action" und geben Sie den Endpunkt für die URL-Benachrichtigung an.
     Klicken Sie hier, um mehr über URL-Benachrichtigung Aktionen zu erfahren..
   • (C) Weisen Sie der Aktion mithilfe der Dropdown-Felder die Bedingung zu und klicken Sie auf "Create rule".
     
     
   
   
   
6. Stellen Sie sicher, dass die Regel aktiv ist (dies wird durch ein Häkchen unter dem Feld Aktiv Spalte). Sobald die Regel aktiviert ist, wird sie auf alle Zahlungsvorgänge für die angegebene sitereference, und die URL-Benachrichtigung wird ausgelöst, sobald die angegebene Bedingung erfüllt ist.
   
   Hinweis: Alle neuen Regeln sollten auf Ihrem Testsystem erstellt werden sitereference und getestet, um sicherzustellen, dass sie wie erwartet funktionieren, bevor sie in Ihr Live-System aufgenommen werden sitereference.
   
   
7. Sie muss Ihr System so konfigurieren, dass es auf alle URL-Benachrichtigungen , die von Trust Payments empfangen werden, mit einer HTTP 200 OK response.
   Zum Beispiel: “HTTP/1.0 200 OK”.
   Ihr System muss innerhalb von 8 Sekunden nach Erhalt einer Benachrichtigung antworten.