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

Met onze SDK kun je ook betalingen naar de Trust Payments verwerken, terwijl je je eigen weergave voor het afrekenen van betalingen gebruikt.

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

2. Initialiseer de Android SDK in uw app

De instantie configureren

Voordat je kunt beginnen met het accepteren van betalingen, moet je eerst een instantie van onze SDK aanmaken PaymentTransactionManager klasse.

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

Locatie Toestemming

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.

Vul het volgende in om de kans te verkleinen dat uw klanten door de kaartuitgever worden uitgedaagd voor verdere verificatie:

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 om GPS in te schakelen als dit momenteel is uitgeschakeld door het apparaat van de klant.
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 uw app toestemming geeft voor toegang tot de apparaatlocatie, probeert de SDK de apparaatlocatie vast te leggen. Raadpleeg voor best practices voor het genereren van de toestemmingsprompt voor de apparaatlocatie De officiële best practices van Google.

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

Aangepaste betalingsweergave

Voor integrators die al een eigen betaalweergave hebben of van plan zijn te bouwen waarmee ze de kaartgegevens van de klant kunnen vastleggen, kunt u doorgaan naar het gedeelte 'Een betaling verwerken' waar we uitleggen hoe u een betaalsessie aanmaakt en het betalingsverzoek naar onze gateway voor betalingsverwerking uitvoert.

Drop-In Payment View

De SDK wordt geleverd met een eigen Drop-In Payment View waarmee je snel kaartgegevens kunt toevoegen aan je kassa. Om onze standaard Drop-In Payment View op te blazen, voeg je deze eerst toe aan een geschikt XML-bestand:

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

Vervolgens moet een activiteit met betrekking tot deze lay-out de vereiste listener-interface implementeren en de methoden van de Drop-In Payment View overschrijven. Dit zorgt ervoor dat de kaartgegevensvariabelen worden bijgewerkt wanneer de kaartgegevens van de klant met succes zijn gevalideerd.

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

 Een betaling verwerken

Om een betaling aan te vragen, maak je eerst een betaalsessie aan door de optie createSession methode, die de volgende argumenten meekrijgt:

Bel de uitvoerenSession methode, die de volgende argumenten meekrijgt:

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

Antwoord betaling verifiëren

De betalingsrespons komt terug als een JSON Web Token (JWT). Het is noodzakelijk dat de handtekening van het JWT-antwoord wordt gevalideerd voordat de inhoud wordt vertrouwd. Net als bij het betalingsverzoek JWT, moet de verificatie van de handtekening plaatsvinden op je beveiligde server.

Neem voor meer informatie over het valideren van de respons JWT even de tijd om het kopje 'De respons JWT-handtekening verifiëren' in onze JWT-leidraad te bekijken .

Zodra de handtekening met succes is geverifieerd en je hebt bevestigd dat het AUTH verzoek met succes is verwerkt, kun je doorgaan met het bijwerken van het app scherm om de klant op de hoogte te stellen.

/**
* 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()
    }
  }
}

Volledig voorbeeld

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 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. Aanmelden bij Portal.
   
   
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.