Aan de slag met Android SDK

Kenmerken

Met de Trust Payments Android SDK kun je naadloos een kant-en-klare of aangepaste UI in je app integreren om kaartbetalingen te accepteren en te voldoen aan het Strong Customer Authentication (SCA) mandaat.

Gebruik deze integratie als u een vooraf gebouwde "Drop-In" UI nodig hebt die de volgende functies ondersteunt:

• Kaartbetalingen
• tokenisatie betalingen
• Aanpassing van UI-componenten aan de huisstijl van uw bedrijf
• Lokale en aangepaste vertalingen

Als u in uw Android app al uw eigen betaalkassaweergaven hebt gebouwd, maar een methode nodig hebt om betalingen naar de Trust Payments gateway te verwerken, kunt u onze Beheerder van betalingstransacties API gebruiken.

  Klik hier voor meer informatie.

1. Installeer de SDK in uw app

Om de Mobile SDK in je project op te nemen, moet je gebruik maken van Gradle, een bouwautomatiseringsprogramma dat functies voor afhankelijkheidsbeheer biedt:

SDK artefacten integreren als een afhankelijkheid van Maven

Voeg in je app-level build.gradle bestand de volgende afhankelijkheden toe:

// 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>'

Om de Mobile SDK te integreren, voegt u de volgende afhankelijkheden toe aan uw app-level build.gradle bestand:

Voeg in je build.gradle bestand op root-niveau de volgende afhankelijkheid toe om de Cardinal SDK te krijgen.

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

SDK integreren in uw project met behulp van de broncode

Als je de broncode van de SDK in je project wilt integreren, neem dan zowel de Core- als de UI-module op.

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

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

Voeg in je build.gradle bestand op root-niveau de volgende afhankelijkheid toe om de Cardinal SDK te krijgen.

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. Initialiseer de Android SDK in uw app

De instantie configureren

Voordat u een betalingsverzoek kunt uitvoeren, moet een instantie van PaymentTransactionManager nodig is. Om het te instantiëren moet u de toepassingscontext opgeven en de gebruikersnaam en de gateway instellen. Je moet ook een waarde opgeven voor isCardinalLive vlag (indien ingesteld op waar, worden alle 3-D Secure-gerelateerde operaties gericht op de 3-D Secure live omgeving, anders wordt de staging omgeving gebruikt). De parameter, cardinalStyleManageris optioneel en maakt het mogelijk de UI aan te passen voor 3-D Secure views. isLocationDataConsentGiven parameter geeft aan de SDK aan of uw app toestemming heeft gekregen van de klant om de locatie van zijn apparaat vast te leggen als onderdeel van het privacybeleid van uw app. Voorbeeld PaymentTransactionManager constructorgebruik hieronder:

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

Vanaf v2.7.10.1 van de Android SDK hebben we een extra parameter toegevoegd aan de SDK's PaymentTransactionManager klasse genaamd isLocationDataConsentGiven. Standaard, isLocationDataConsentGiven is ingesteld op false, wat betekent dat de klant niet heeft ingestemd met het privacybeleid van uw app waarin toestemming wordt gevraagd om de locatiegegevens van het apparaat vast te leggen. De informatie die nodig is om het privacybeleid aan de klant te tonen kan worden gevonden hier.

Om de kans te verkleinen dat uw klanten door de kaartuitgever worden uitgedaagd voor verdere verificatie, moet u het volgende invullen:

1. Zodra uw klant heeft ingestemd met het privacybeleid van uw app, dat ook locatiegegevens omvat, moet de toestemming voor het privacybeleid van uw app worden doorgegeven aan de Trust Payments SDK. PaymentTransactionManager instantie door de instelling isLocationDataConsentGiven als waar. 

2. Verzoek dat GPS kan worden ingeschakeld indien deze momenteel door de app-klant is uitgeschakeld.
3. Maak een locatie toestemmingsprompt wanneer uw app een instantie van de PaymentTransactionManager klasse. U moet machtigingen opnemen in het manifestbestand:
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
Als de klant toestemming voor toegang tot de apparaatlocatie heeft verleend aan uw app, zal de SDK proberen de apparaatlocatie vast te leggen. Raadpleeg de officiële best practices van Google voor best practices voor het genereren van de toestemmingsprompt voor de apparaatlocatie: https://support.google.com/googleplay/android-developer/answer/11150561

Voor een voorbeeld van hoe je het privacybeleid aan klanten kunt presenteren in je app voor acceptatie door de klant, kun je onze voorbeeldtoepassingsklasse raadplegen PrivacyPolicyActivity.kt

Blaas de Drop-In Payment View

Om onze standaard Drop-In Payment View op te blazen, moet u deze toevoegen aan een geschikt XML-bestand:

<?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>

Vervolgens moet een aan deze lay-out gerelateerde activiteit de vereiste listener interface implementeren en de voor deze Drop-In Payment View voorziene methoden overschrijven. Die methoden zullen alle nodige gegevens verstrekken om de PaymentTransactonManager en een transactie verwerken.

Voorbeeld:

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

Beheerder van betalingstransacties

Als u al uw eigen betaalkassaweergaven in uw Android app hebt of van plan bent te bouwen, maar een methode nodig hebt om betalingen aan de Trust Payments gateway te verwerken, kunt u onze Beheerder van betalingstransacties API gebruiken.

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

paymentTransactionManager.executeSession(paymentSession, activityProvider)

Bij het oproepen van de paymentTransactionManager.executeSession methode en ook het specificeren van THREEDQUERY in de JWT payload requesttypedescriptions veldlijst, moet u ervoor zorgen om executeSession met parameter activityProvider. De activityProvider is een callback naar een Activity. De Activity zou het venster in uw Android app zijn en dit moet bekend zijn bij onze betalings SDK om met succes het 3-D Secure versie 2 native challenge venster aan uw klanten te tonen.

In onze Gitlab repository hebben we verschillende app voorbeelden en het volgende gelinkte voorbeeld demonstreert hoe u een pay by card met 3-D Secure oplossing zou configureren. Klik hier om dit in een nieuw tabblad te openen.

3. Webhooks configureren

Het wordt sterk aanbevolen om webhooks te configureren op uw Mobile SDK-oplossing. Indien geconfigureerd, wordt URL-kennisgevingen naar uw systeem gestuurd wanneer betalingen op uw rekening worden verwerkt.

1. Log in op MyST.
   
   
2. Zoek naar uw sitereference met behulp van het zoekvak bovenaan de pagina.
   
   
3. Wanneer u de details van uw site bekijkt, klikt u op "Regelbeheer".
   
   
   
   
4. Selecteer het actietype "URL-kennisgeving" uit het keuzemenu en uw browser wordt omgeleid.
   
   
   
   
5. Maak een nieuwe URL-kennisgeving regel aan:
   • (A) Klik "Add new condition" en de omstandigheden specificeren waaronder de URL-kennisgeving na een transactie in werking moet worden gesteld. In de Verzoeken box weergegeven, zorg ervoor dat "AUTH" is aangevinkt (wat betekent dat de kennisgeving wordt geactiveerd na betaling authorisaties).
     Klik hier voor meer informatie over het configureren van voorwaarden.
   • (B) Klik op "Add new action" en geef het eindpunt voor de URL-kennisgeving.
     Klik hier voor meer informatie over URL-kennisgeving acties.
   • (C) Wijs met behulp van de vervolgkeuzelijsten de voorwaarde toe aan de actie en klik op "Create rule".
     
     
   
   
   
6. Zorg ervoor dat de regel actief is (dit wordt aangegeven met een vinkje onder het Actief kolom). Na activering wordt de regel toegepast op alle betalingssessies voor de opgegeven sitereference, en de URL-kennisgeving wordt geactiveerd wanneer aan de gespecificeerde voorwaarde wordt voldaan.
   
   Opmerking: Alle nieuwe regels moeten worden aangemaakt op je test sitereference en getest om er zeker van te zijn dat ze werken zoals verwacht voordat ze worden toegevoegd aan uw live sitereference.
   
   
7. Jij moet configureer uw systeem om te reageren op alle URL-kennisgevingen ontvangen van Trust Payments met een HTTP 200 OK response.
   Bijvoorbeeld: “HTTP/1.0 200 OK”.
   Uw systeem moet binnen 8 seconden na ontvangst van een melding antwoorden.