Integration Types
Other Features
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
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 projects build.gradle
file.
For more information about downloading the SDK, see Mobile SDK Integration.
build.gradle
file.// build.gradle allprojects { repositories { mavenCentral() google() // Gateway Android SDK repo maven { url "$rootDir/gateway-repo" } } }
build.gradle
file, include the Gateway SDK as a dependency.// app/build.gradle implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'
The Mobile_SDK_Android
folder contains a maven-metadata.xml
file that has information to build the implementation reference for the library.
The implementation gradle format is implementation <groupId>:<artifactId>:<version>
Initialize the Android SDK before using it. It is recommended to perform this operation 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", "Your gateway region", callback ) }
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. For more information, see Payment Session documentation.
Create a session with the gateway to initiate the payment flow on a mobile device.
Request Parameter | Example |
---|---|
authenticationLimit | 25 |
Request Parameter | Existence | 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 |
Once a session is created on your server, you should
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 )
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 and must be present in the session before the call is made in the SDK to authenticate the payer.
Pass the information directly to the gateway using an existing Session ID.
// 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);
The SDK provides support to update a session with card information, 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.
Follow these steps to use the mobile SDK to facilitate creating a card token.
GatewayAPIupdateSession
method.For more information about Tokenization, see Create or Update Token documentation.
The Gateway SDK includes a helper utility, called GooglePayHandler, for collecting card information from a Google Pay wallet.
To enable Google Pay support within your app, see the Google Pay documentation.
These instructions should guide you on how to:
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.
To request encrypted card information from Google Pay
mpgs
in your request, andYOUR_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"))
Use the GooglePayHandler
to launch the Google Pay wallet with your constructed payments client and request data.
// 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() } }
The Gateway SDK offers a Google Pay lifecycle handler for convenience. You may implement the provided Google Pay callback and use the result handler within your activity.
This eliminates the need to manually handle the Google Pay activity results and delegates 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 } }
Update a session with the gateway once you receive payment data from Google Pay.
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) }
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.
The 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, or previous interactions or both, 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 do so.
For more information about 3D Secure Authentication, see 3-D Secure Authentication documentation.
The embedded mobile SDK collects device metrics to send to the gateway along with your transaction information when you perform mobile SDK authentication, that is, verify the identity of a cardholder in a mobile app.
Provide as much information as possible about the payer and the transaction to increase the likelihood of the authentication being successful.
This additional information can be added to your session
with an Update session request.
Parameter | Existence | Description |
---|---|---|
order.merchantCategoryCode | Optional | Same as the code in your merchant profile |
billing.address parameter group | Optional | It is strongly recommended you include this in your request whenever possible |
shipping.address parameter group | Optional | It is strongly recommended you include this in your request whenever possible |
customer parameter group | Optional | It is strongly recommended you include this in your request whenever possible |
device
parameter group as seen in the documentation is only relevant for browser based payments.
It should not be used for mobile based payer authentications.These metrics help the system to determine how or if to authenticate the cardholder. During authentication, the user can expect to experience one of two auth flows:
UICustomization
params into the Gateway SDK during initialization.For more information, see Authenticate Payer documentation.
authentication.PSD2.exemption
is currently not supported in the SDK. Payer authentication is considered a transaction on its own in the gateway, and therefore needs a unique transaction ID.
If you are collecting payment for an order, you can
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id
is a unique identifier for this transaction which distinguishes 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 then passes the required information to the acquirer for the pay request.The authenticate
method will return an AuthenticationResponse
object that contains:
The most important field to consume is response.recommendation
. It may contain the value PROCEED
or DO_NOT_PROCEED
.
AuthenticationError
object can be used to determine more.From Gateway API version 70 and above, you can get the following errors:
AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails
: Indicates that you should ask the payer for alternative payment details. For example, 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 way for this transaction to succeed.For more information, see the Integration guides.
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 fails, you can examine the response.error
, for more information about the cause.