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
• Google Pay

Alternativ können Sie mit unserem SDK Zahlungen über das Trust Payments Gateway abwickeln, während Sie Ihre eigene Kassenansicht verwenden.

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)
      }
    }
  }
}

2. Initialisieren Sie das Android SDK in Ihrer Anwendung

Konfigurieren Sie die Instanz

Bevor Sie mit der Annahme von Zahlungen beginnen können, müssen Sie zunächst eine Instanz unseres SDK erstellen PaymentTransactionManager Klasse.

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

Standort Zugelassen

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 die folgenden Schritte ausführen:

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 auf dem Kundengerät deaktiviert ist.
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 Anwendung die Erlaubnis zum Zugriff auf den Gerätestandort erteilt hat, versucht das SDK, den Gerätestandort zu erfassen. Bewährte Vorgehensweisen für die Generierung der Aufforderung zur Zustimmung zum Gerätestandort finden Sie unter Die offiziellen Best Practices von Google.

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

Benutzerdefinierte Zahlungsansicht

Für Integratoren, die bereits eine eigene Zahlungsansicht erstellt haben oder dies planen, die in der Lage ist, die Kartendaten des Kunden zu erfassen, können Sie mit dem Abschnitt "Eine Zahlung verarbeiten" fortfahren, in dem erklärt wird, wie eine Zahlungssitzung erstellt und die Zahlungsanforderung an unser Zahlungsabwicklungs-Gateway ausgeführt wird.

Drop-In Payment View

Das SDK wird mit einer eigenen Drop-In Payment View geliefert, die es Ihnen ermöglicht, die Eingaben für die Kartendetails schnell in Ihren Checkout einzufügen. Um unsere standardmäßige Drop-In Payment View aufzublasen, fügen Sie sie zunächst zu einer entsprechenden XML-Datei hinzu:

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

Als Nächstes muss eine Aktivität, die sich auf dieses Layout bezieht, die erforderliche Listener-Schnittstelle implementieren und die Methoden der Drop-In Payment View außer Kraft setzen. Dadurch wird sichergestellt, dass die Variablen für die Kartendetails aktualisiert werden, wenn die Kundenkartendaten erfolgreich validiert wurden.

class SimpleActivity : AppCompatActivity(), DropInPaymentView.DropInPaymentViewListener {

    // Payment card details.
    private var pan = ""
    private var expiryDate = ""
    private var cvv = ""

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_simple)
        // Set the drop-in payment view listener
        findViewById(R.id.dropInPaymentView).dropInPaymentViewListener = this
    }

    /**
     * Captures user input from payment view and update variables if input is valid.
     * */
    override fun onInputValid(paymentInputType: PaymentInputType, input: String) {
        when (paymentInputType) {
            PaymentInputType.PAN - pan = input
            PaymentInputType.ExpiryDate - expiryDate = input
            PaymentInputType.CVV - cvv = input
        }
    }

    /**
     * Get called once card details is provided in payment view and pay button is clicked.
     * */
    override fun onPayButtonClicked() {
        processTransaction(pan = pan, expiryDate = expiryDate, cvv = cvv)
    }
}
  

 Eine Zahlung verarbeiten

Um eine Zahlung anzufordern, erstellen Sie zunächst eine Zahlungssitzung, indem Sie die createSession Methode, die die folgenden Argumente enthält:

Sobald Sie Ihre Zahlungsvereinbarung haben, rufen Sie die ausführen.Session Methode, die die folgenden Argumente enthält:

 private fun processTransaction(pan: String, expiryDate: String, cvv: String) {
  lifecycleScope.launch(Dispatchers.IO) {
	// Obtain generated JWT from client server, This contains payment order information that you are planning to pay.
	val jwt: String = fetchJwtFromServer()
	// Create payment session which contains order and payment information.
	val session: PaymentSession = paymentTransactionManager.createSession(
		jwtProvider = { jwt },
		cardPan = pan,
		cardExpiryDate = expiryDate,
		cardSecurityCode = cvv,
	)
	// Executes payment request using PaymentTransactionManager. Once completed response will be presented.
	val response: Response = paymentTransactionManager.executeSession(
		session = session,
		activityProvider = {
			this@SimpleActivity
		},
	)
	// Validate payment result and update screen with the transaction details.
	processResponse(response)
  }
}

Überprüfung der Zahlungsantwort

Die Antwort auf die Zahlung kommt als JSON Web Token (JWT) zurück. Es ist unbedingt erforderlich, dass die Signatur der JWT-Antwort überprüft wird, bevor Sie ihrem Inhalt vertrauen. Wie beim JWT der Zahlungsanforderung sollte die Überprüfung der Signatur auf Ihrem sicheren Server stattfinden.

Um mehr darüber zu erfahren, wie Sie die Antwort-JWT validieren können, nehmen Sie sich bitte einen Moment Zeit und lesen Sie die Überschrift "Überprüfen der Antwort-JWT-Signatur" in unserer JWT-Anleitung.

Sobald die Signatur erfolgreich geprüft wurde und Sie bestätigt haben, dass die AUTH erfolgreich bearbeitet wurde, können Sie den App-Bildschirm aktualisieren, um den Kunden zu benachrichtigen.

/**
* Validates executed payment result and update screen with the transaction details.
* */
private suspend fun processResponse(response: Response) {
  // Verify JWT signature from response on your server
  if (verifyJwtSignatureUsingYourServer(response.responseJwtList)) {
    val parsedResult = ResponseParser.parse(response.responseJwtList)
    val transactionReference =
      parsedResult?.firstOrNull()
      ?.customerOutput?.transactionReference
    withContext(Dispatchers.Main) {
      Toast.makeText(
        this@SimpleActivity,
        "Transaction Successful: $transactionReference",
          Toast.LENGTH_LONG
      ).show()
    }
  }
}

Vollständiges Beispiel

package com.trustpayments.mobile.exampleapp

import JwtProvider.fetchJwtFromServer
import JwtProvider.verifyJwtSignatureUsingYourServer
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
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
import com.trustpayments.mobile.core.services.transaction.PaymentTransactionManager.Response
import com.trustpayments.mobile.core.util.ResponseParser
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

class SimpleActivity : AppCompatActivity(), DropInPaymentView.DropInPaymentViewListener {

    // PaymentTransactionManager responsible for executing the transaction.
    private val paymentTransactionManager by lazy {
        PaymentTransactionManager(
            context = applicationContext,
            gatewayType = TrustPaymentsGatewayType.EU,
            isCardinalLive = false, // Mark this true for production mode.
            merchantUsername = BuildConfig.MERCHANT_USERNAME, // MERCHANT_USERNAME obtained through account manager
            isLocationDataConsentGiven = true,
        )
    }

    // Payment card details.
    private var pan = ""
    private var expiryDate = ""
    private var cvv = ""

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_simple)
        // Set the drop-in payment view listener
        findViewById(R.id.dropInPaymentView).dropInPaymentViewListener = this
    }

    /**
     * Captures user input from payment view and update variables if inputs are valid.
     * */
    override fun onInputValid(paymentInputType: PaymentInputType, input: String) {
        when (paymentInputType) {
            PaymentInputType.PAN - pan = input
            PaymentInputType.ExpiryDate - expiryDate = input
            PaymentInputType.CVV - cvv = input
        }
    }

    /**
     * Gets called once card details are provided in payment view and pay button is clicked.
     * */
    override fun onPayButtonClicked() {
        processTransaction(pan = pan, expiryDate = expiryDate, cvv = cvv)
    }

    private fun processTransaction(pan: String, expiryDate: String, cvv: String) {
        lifecycleScope.launch(Dispatchers.IO) {
            // Obtain generated JWT from client server, This contains payment order information that you are planning to pay.
            val jwt: String = fetchJwtFromServer()
            // Create payment session which contains order and payment information.
            val session: PaymentSession = paymentTransactionManager.createSession(
                jwtProvider = { jwt },
                cardPan = pan,
                cardExpiryDate = expiryDate,
                cardSecurityCode = cvv,
            )
            // Executes payment request using PaymentTransactionManager. Once completed response will be presented.
            val response: Response = paymentTransactionManager.executeSession(
                session = session,
                activityProvider = {
                    this@SimpleActivity
                },
            )
            // Validate payment result and update screen with the transaction details.
            processResponse(response)
        }
    }

    /**
     * Validates executed payment result and update screen with the transaction details.
     * */
    private suspend fun processResponse(response: Response) {
        // Verify JWT signature from response
        if (verifyJwtSignatureUsingYourServer(response.responseJwtList)) {
            val parsedResult = ResponseParser.parse(response.responseJwtList)
            val transactionReference =
                parsedResult?.firstOrNull()
                    ?.customerOutput?.transactionReference
            withContext(Dispatchers.Main) {
                Toast.makeText(
                    this@SimpleActivity,
                    "Transaction Successful: $transactionReference",
                    Toast.LENGTH_LONG
                ).show()
            }
        }
    }
}

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.