Mobile_SDK_Integration_Guide_Android.

md 2024-05-17

Gateway Android SDK

Version: 2.0.12

Contents
Installation
Initialize the SDK
Session Overview
Creating a Session
Collecting Card Information
Manual Card Entry
Card Tokenization
Google Pay
Configuration
Requesting Wallet Info
Handling Wallet Response
Update Session with Payment Token
Payer Authentication
3D Secure
Authentication Details
Performing Authentication
Interpreting the Response

1 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Installation
This SDK is packaged as a maven repository. It should be unzipped to a location in your project, and added
as a repository in your project's build.gradle file.
. From your Gateway Merchant Admin portal, download the latest version of the SDK in ZIP file format.
. Unzip this file in the root directory of your Android project. (ex: ~/my-android-
project/gateway-repo)

. Add a reference to this local repository in your project's build.gradle file.

// build.gradle

allprojects {
repositories {
mavenCentral()
google()

// Gateway Android SDK repo

maven {
url "$rootDir/gateway-repo"
}
}
}

. In your app module's build.gradle file, include the Gateway SDK as a dependency
Note: Replace 'X.X.X' with current version number

// app/build.gradle

implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'

The “maven-metadata.xml” file under the folder Mobile_SDK_Android contains a metadata.xml file,
you can use the information from there to build the implementation reference for the library. The
format of the implementation in Gradle is implementation <groupId>:<artifactId>:
<version>

2 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Security Recommendations for Integrating Our SDK

Update Session Attempts Limitation: Implement session update attempt limitation to prevent brute
force attacks and unauthorized access.
Additional Security Measures:
CAPTCHA Integration: Use CAPTCHA to validate user authenticity and prevent automated
attacks.
Biometric Authentication: Employ fingerprint or face recognition for robust user
authentication and to thwart unauthorized access attempts.
DDoS Protection: Implement robust DDoS protection mechanisms to safeguard against
volumetric attacks and ensure continuous service availability.
Bot Detection: Incorporate advanced techniques to identify and mitigate malicious bot
activities exploiting application vulnerabilities.
Rate Limiting: Enforce strict rate limiting policies to regulate requests from clients or IP
addresses, ensuring fair resource allocation and mitigating abuse.
SSL Pinning with Our Own Server: Include SSL pinning to ensure secure communication,
preventing man-in-the-middle attacks and unauthorized server access. By following these
security recommendations during SDK integration, your mobile application can significantly
enhance its resilience against various threats, providing a secure and trustworthy user
experience.

3 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Initialize the SDK

Before it can be used, the Android SDK must be initialized. It's recommended this operation be performed
in your custom Application class in the onCreate() method.

// CustomApplication.kt

override fun onCreate() {

super.onCreate()

// init Gateway SDK

GatewaySDK.initialize(
this,
"YOUR_MERCHANT_ID",
"Your Merchant Name",
"https://your-merchant-url.com",
GatewayRegion.MTF,
callback
)
}

4 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Creating a Session
Session Overview
The Gateway SDK flow is based around the concept of a session. A session is a temporary container for any
request fields and values of operations that reference a session. See Payment Session documentation for
more information.
Key Benefits
. Reduces PCI compliance costs as you do not handle or store any payment details.
. Facilitates ease of integration as you do not need to directly handle the values for the request fields
stored in a session.
. Reduces internal fraud as your staff has limited access to payer's details.
. Allows you to update the request fields and values stored against a session. This is useful when a
credit card expires or other details of a payer change.
. Allows you to retrieve the request fields and values contained in a session by specifying the session
identifier.

5 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Creating a Session
To initiate the payment flow on a mobile device, you need to create a session with the Gateway. Two API
calls need to be made to prepare this session for mobile transactions. These calls are secured by an API
password and thus need to be called from your private server.
. Create Session
Request Parameter Example
authenticationLimit 25

. Update Session
Request Parameter Existance Example
order.id Required your-order-id

order.amount Required 1.23

order.currency Required AUD

authentication.acceptVersions Required 3DS2

authentication.channel Required PAYER_APP

authentication.purpose Required PAYMENT_TRANSACTION

Note: The above api fields need to be loaded into the session before the call is made in the SDK to
authenticate the payer. How and when they are loaded into the session can be determined by your API
design.

Once a session is created on your server, you should return the session information back to the mobile app
and create an instance of the Session object.

// example
val session = Session(
id = "your-session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "your-order-id" // must match order id used on your server
)

Note: the apiVersion needs to be the same for the whole transaction lifecycle. From Session creation to
final payment.
6 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Collecting Card Information

The SDK method to updateSession is optional to use but is recommended to help with merchant server
PCI scope. However the card and token information can be loaded via a different API design. Please keep in
mind they need to be present in the session before the call is made in the SDK to authenticate the payer.
Manual Card Entry
Using an existing Session Id, you may pass card information directly to the Gateway:

// The GatewayMap object provides support for building a nested map

structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
val request = GatewayMap()
.set("sourceOfFunds.provided.card.nameOnCard", nameOnCard)
.set("sourceOfFunds.provided.card.number", cardNumber)
.set("sourceOfFunds.provided.card.securityCode", cardCvv)
.set("sourceOfFunds.provided.card.expiry.month", cardExpiryMM)
.set("sourceOfFunds.provided.card.expiry.year", cardExpiryYY);

GatewayAPI.updateSession(session, request, callback);

7 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Tokenization
The SDK provides support to update a Session with card information, and you can use that Session to
perform several operations with the Gateway. Tokenization provides a way to retain a card on file, and can
be performed on your server with a valid Session. To use the mobile SDK to facilitate creating a card token,
follow these steps:
. Create and Update a Session using the SDK.
. Update the session with the customers card details via the Gateway SDK. GatewayAPI
updateSession method.
. Return the Session Id to your server and call the Create or Update Token method on the Gateway with
your private API credentials.
. A token id is returned and can be retained on your servers as a card-on-file.
See Create or Update Token documentation

8 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Google Pay
The Gateway SDK includes a helper utility (GooglePayHandler) for collecting card information from a
Google Pay wallet.
Configuration
To enable Google Pay support within your app, refer to the Google Pay Documentation. These instructions
should guide you in how to:
Set up the Google Pay API
Request payment information from the Google wallet
Incorporate the button into your layout
Handle the response from the Google Pay API
Since Google Pay integration is optional with the Gateway SDK, you must provide the appropriate play
services dependency.

implementation 'com.google.android.gms:play-services-wallet:X.X.X'

The Gateway is integrated with Google Pay as a PAYMENT_GATEWAY type. In order to request encrypted
card information from Google Pay, you must use the valid name mpgs in your request. Be sure to replace
YOUR_MERCHANT_ID with the merchant ID you use on the Gateway.

val tokenizationSpecification = JSONObject()

.put("type", "PAYMENT_GATEWAY")
.put("parameters", JSONObject()
.put("gateway", "mpgs")
.put("gatewayMerchantId", "YOUR_MERCHANT_ID"))

9 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Requesting Wallet Info

With your constructed payments client and request data, you may use the GooglePayHandler to launch
the Google Pay wallet.

// YourActivity.kt

fun googlePayButtonClicked() {
try {
val request =
PaymentDataRequest.fromJson(paymentDataRequest.toString())

// use the Gateway convenience handler for launching the Google

Pay flow
GooglePayHandler.requestData(this, paymentsClient, request)

} catch (e: JSONException) {

Toast.makeText(this, "Could not request payment data",
Toast.LENGTH_SHORT).show()
}
}

10 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Handling Wallet Response

The Gateway SDK offers a Google Pay lifecycle handler for added convenience. You may implement the
provided Google Pay callback and use the result handler within your Activity. This alleviates the need to
manually handle the Google Pay activity results, and will delegate the important transaction steps to the
callback methods.

// YourActivity.kt

override fun onActivityResult(requestCode: Int, resultCode: Int, data:

Intent?) {
// handle the Google Pay response
if (GooglePayHandler.handleActivityResult(requestCode, resultCode,
data, callback)) {
return
}

super.onActivityResult(requestCode, resultCode, data)

}

val googlePayCallback = object : GooglePayCallback {

override fun onReceivedPaymentData(paymentData: JSONObject) {
try {
val description =
paymentData.getJSONObject("paymentMethodData")
.getString("description")

Log.d(MyGooglePayCallback::class.java.simpleName,
"ReceivedPaymentData: $description")
} catch (e: Exception) {
// handle exception
}

handleGooglePayData(paymentData)
}

override fun onGooglePayCancelled() {

// handle cancelled
}

override fun onGooglePayError(status: Status) {

// handle error
}
}

11 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Update Session with Payment Token

Once you have received payment data from Google Pay, you may use it to update a session with the
Gateway.

fun handleGooglePayData(paymentData: JSONObject) {

val token = paymentData.getJSONObject("paymentMethodData")
.getJSONObject("tokenizationData")
.getString("token")

val request = GatewayMap()

.set("sourceOfFunds.provided.card.devicePayment.paymentToken",
token)

GatewayAPI.updateSession(session, request, callback)

}

12 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Payer Authentication
3D Secure
3-D Secure or 3DS authentication is designed to protect online purchases against credit card fraud by
allowing you to authenticate the payer before submitting an Authorization or Pay transaction.
EMV 3DS, also known as 3DS2 in the gateway, is the new version designed to enhance security in online
purchases while providing frictionless checkouts to payers who are considered low risk by the Access
Control Server (ACS). The ACS may determine the risk using information provided by the merchant, device
fingerprinting, and/or previous interactions with the payer. The ACS subjects the payer to a challenge (for
example, entering a PIN) only where additional verification is required to authenticate the payer thereby
providing increased conversion rates. Supported authentication schemes include Mastercard Identity
Check, Visa Secure, and American Express SafeKey.
Authentication within the mobile SDKs is limited to 3DS2 only. If 3DS2 is not available, the authentication
will not proceed. However, you can still proceed with the payment if the gateway recommends you to do so.
For more detailed documentation plese see 3-D Secure Authentication

13 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Authentication Details
When you perform EMV 3DS authentication (i.e. verify the identity of a cardholder) in a mobile app, the
embedded 3DS SDK collects device metrics to send to the Gateway along with your transaction
information.
To increase the likelihood of the authentication being successful, provide as much information about the
payer and the transaction as possible. This additional information can be added to your session with an
Update Session request.
Parameter Existance Description
order.merchantCategoryCode Optional Same as the code in your merchant profile
billing.address parameter It is strongly recommended you include this in your
group Optional request whenever possible
shipping.address parameter It is strongly recommended you include this in your
group Optional request whenever possible
customer parameter group Optional Itrequest
is strongly recommended you include this in your
whenever possible
* The device parameter group as seen in the documentation is only relevent for browser based payments.
It should NOT be used for mobile based payer authentications.

These metrics help the system determine how/if to authenticate the cardholder. During authentication, the
user can expect to experience one of two auth flows:
. Frictionless: The ACS has collected enough information about the cardholder to authenticate them.
No other action is needed by the user.
. Challenge: The ACS requires the cardholder complete an additional authentication step (enter a one-
time-password, login to their issuing bank, etc.) The embedded 3DS SDK handles displaying a native
device interface for this challenge. The UI for these screens can be customized by passing
UICustomization params into the Gateway SDK during initialization.

For more detailed documentation plese see Authenticate Payer

Note: The parameter group for authentication.PSD2.exemption is currently not supported in the
SDK

14 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

Performing Authentication
Payer authentication is considered its own transaction in the Gateway, and therefore needs a unique
transaction ID. If you are collecting payment for an order, you can correlate a payment and an authentication
transaction by using the same order ID for each, but each will be displayed as separate transactions in the
Gateway's web portal. Such as a UUID.

AuthenticationHandler.authenticate(activityContext, session, "your-auth-

transaction-id", callback)

Note: the your-auth-transaction-id is a unique identifier for this transaction to distinguish it from any
other transaction on the order. This is needed as the gateway will use the your-auth-transaction-id
to look up the authentication results that it stored when you asked the SDK to authenticate the payer. The
gateway will then pass the required information to the acquirer for the pay request.
Interpreting the Response
The authenticate method will return an AuthenticationResponse object containing important
information about the outcome, as well as what actions were performed during the operation.
The most important field to consume is response.recommendation. It may contain the value proceed
or doNotProceed. You may interpret proceed as "OK to continue with a payment or authorization". A
value of doNotProceed would indicate that something failed during the authentication operation. The
AuthenticationError object can be used to determine more.

From Gateway API version 70+ you can get an error of

AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails
which indicates that you should ask the payer for alternative payment details (e.g. a new card or
another payment method) and resubmit the request with the new details.
AuthenticationError.recommendation_AbandonOrder indicates the payment service
provider, scheme or issuer require you to abandon the order.
AuthenticationError.recommendation_DoNotProceed indicates the gateway fails the
request, but there is no apparent way for this transaction to succeed.

15 / 16
Mobile_SDK_Integration_Guide_Android.md 2024-05-17

See the integration guides for more information.

AuthenticationHandler.authenticate(activityContext, session, "your-auth-

transaction-id") { response ->
when(response.recommendation) {
AuthenticationRecommendation.PROCEED -> {
// continue to payment/authorization
}
AuthenticationRecommendation.DO_NOT_PROCEED -> {
if (response.error != null) {
if (response.error is
AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
// "Authentication not successful, re-enter card
details
}
} else {
// "Authentication not successful"
}
}
}
}

If the authentication failed you can examine the response.error for more information about the cause.

16 / 16