# Masterpass Checkout Android SDK - v2.6 source: https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v26/index.md This page contains details of version of the Masterpass Checkout Android SDK, version 2.6 - this is not the latest version. Check the main integration page to find a link to the latest release of the SDK. ## Overview {#overview} The Masterpass Checkout Android SDK is designed to enable you to add Masterpass checkout services into your native Android apps quickly and easily. You can integrate Masterpass for the "Standard Checkout" and "Express Checkout" flows, and can use the Masterpass Button or Payment method selection. The SDK offers the following integration options: * **Standard Checkout** : With Standard Checkout, your checkout screen will contain the Masterpass button, which when tapped will redirect the consumer to the Masterpass checkout experience. The checkout experience can be entirely within the app (in supported countries) called the[merchant embedded experience](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/merchant-embedded-native-experience/index.md) , or via the web. * **Payment Method**: The payment method flow is similar to the Standard Checkout flow, except that the consumer selects a payment method from a list before launching the Masterpass checkout experience from a standard UI element rather than an explicit Masterpass button. * **Express Checkout**: With Express Checkout, consumers have the option to pair their payment details / wallets with you so that future checkouts are more seamless. **Note: Express Checkout is not supported in the US, Canada and India. Please contact your regional representative for more information.** The steps needed to implement both of these are described below. ## Onboarding {#onboarding} To complete onboarding for the Masterpass Checkout Android SDK, you must complete the following steps: 1. Complete the standard Masterpass onboarding steps. 2. To allow the Masterpass web checkout experience to return control to the app, add a callback URL to your Masterpass project on Mastercard Developers under Checkout Credentials. The URL should be formatted as follows: "intent://masterpass/#Intent;scheme=com.mastercard.merchant;package=\*merchant.app.package.name;\*end". The portion in italics indicates the package name of your Android app. 3. Select "Android" as the Channel for the Checkout ID (this is also set in the Checkout Credentials tab on Mastercard Developers). In addition, note that before being enabled for Express Checkout, merchants must pass the Masterpass security vetting specifications. The following steps outline the way in which Express Checkout should work: 1. The merchant must have a reliable method for identifying the consumer, preferably with login. 2. The consumer must log in to their merchant account and pair it with their Masterpass wallet account. This allows Masterpass to share the consumer's wallet data with the merchant during checkout. 3. The merchant requests a masked copy of the wallet data (known as precheckout data) from Masterpass to display on their site or app. 4. The consumer makes their payment and shipping selections on the merchant interface and clicks the Masterpass Button to confirm the order. 5. The merchant (or their Payment Service Provider) receives the full, unmasked payment details from the Masterpass wallet and uses that information to process the order. ## SDK download {#sdk-download} The SDK is available for download from here: | Zip file | Contents | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [masterpass-merchant-android-sdk-v2.6.1.zip](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/uploads/masterpass-merchant-android-sdk-v2.6.1.zip) | Masterpass SDK libraries:- masterpass-core-2.6.1.aar- masterpass-merchant-2.6.1.aarAdditional libraries:- devicelevelauthentication-1.0.1.aarSample application Source code project for sample application. Refer to Read.MD in SampleApp_v2.6.1 for instructions about how to configure the sample application.Last Updated: September 3rd 2018 | Two Masterpass libraries (.aar files) are provided: * Core - com.mastercard.mp.checkout:masterpass-core:2.6.x@aar * Merchant - com.mastercard.mp.checkout:masterpass-merchant:2.6.x@aar The Merchant library builds on (and has a dependency on) the Core library. The following additional libraries are included: * devicelevelauthentication-1.0.1.aar - needed for biometric / fingerprint support ## What's new in this release? {#whats-new-in-this-release} The following changes and new features in version 2.6.x of the Masterpass Checkout Android SDK, compared to version 2.5: * PIN authentication is now enabled for Indian consumers. * AFA Relaxation - 3D Secure checks can be relaxed for Indian consumers for purchases under 2000 Rupees in certain cases. * The Merchant embedded native experience is now enabled in the following additional countries / locales: French Canadian, India, Thailand. * Consumers no longer need to opt-in for biometrics. Masterpass will now automatically enroll consumers for this feature if a merchant has enabled biometrics. ### Previous releases {#previous-releases} * [Masterpass Checkout Android SDK v2.5](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v25/index.md) * [Masterpass Checkout Android SDK v2.4](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v24/index.md) * [Masterpass Checkout Android SDK v2.0](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v2/index.md) ## Migration notes {#migration-notes} The following important changes to the SDK in this release will require you to make code changes in your merchant app: * The SDKs and sample application are compatible with new gradle plugin version 3.0+. See the [android documentation](https://developer.android.com/studio/build/) for details * The Card.io library is no longer built into the bundle dependencies. A merchant application developer needs to add the following external dependency into the application build.gradle: implementation **'io.card:android-sdk:5.5.0'** **Note**: If migrating from an earlier version, refer to the migration notes for all intervening releases at the links above. ## Using the merchant library {#using-the-merchant-library} This integration tutorial goes through the typical steps involved to demonstrate how you can add Masterpass to your Android merchant app. ### Importing the SDK {#importing-the-sdk} * Java ```Java dependencies { compile 'com.mastercard.mp.checkout:masterpass-core:2.6.1@aar' compile 'com.mastercard.mp.checkout:masterpass-merchant:2.6.1@aar' } ``` Ensure your project also correctly uses the devicelevelauthentication-1.0.1.aar library. If using Proguard, certain rules must be added to prevent runtime errors related to code obfuscation. Please include the following rules in your proguard-rules.pro file. * XML ```XML -dontwarn javax.xml.stream.events.** -dontwarn javax.xml.stream.** -keep class * implements android.os.Parcelable { public static final android.os.Parcelable$Creator *; } -assumenosideeffects class android.util.Log { public static *** d(...); public static *** v(...); } ``` ### Initializing the SDK {#initializing-the-sdk} * Java ```Java MasterpassMerchant.initialize(masterpassMerchantConfiguration, masterpassInitCallback); ``` The **MasterpassMerchantConfiguration** class defines the settings you wish to configure the SDK with, such as the environment you wish to use, the locale, etc. | **Parameter** | **Description** | |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | environment | Name of the environment to which the SDK should point. Currently the available environments are: SANDBOX and PRODUCTION. | | locale | The application locale. Note that this is used by the SDK when deciding whether to use the native checkout experience or the web checkout experience (as initially not all regions will support native checkout). | | merchantName | The merchant name used while registering the merchant application on the Masterpass portal. | | expressCheckoutEnabled | Boolean flag specifying whether the app is enabled for express checkout. | | checkoutId | Merchant checkout identifier received when merchant onboarded for Masterpass. | Refer to the sample merchant initialization code below for further details on constructing **MasterpassMerchantConfiguration** and implementing a **MasterpassInitCallback** interface. This will need to provide code for handling **onInitSuccess()** and **onInitError()** responses. ### Show MasterpassButton {#show-masterpassbutton} When a user is ready to checkout, you can show them the MasterpassButton in order to checkout using the SDK. * Java ```Java ImageButton bwmpButton = MasterpassMerchant.getMasterpassButton(behavior, masterpassCheckoutCallback); buttonHolderView.addView(bwmpButton); ``` You will need to implement a **CheckoutListener** interface and pass this as **masterpassCheckoutCallback** . Your listener must implement **onCheckout()**. ### Configure MasterpassButton behavior. {#configure-masterpassbutton-behavior} There are two options when calling the **getMasterpassButton()** method, indicated by the value of **behavior**: #### 1. PAIRING_CHECKOUT_FLOW_ENABLED {#1-pairing_checkout_flow_enabled} This option is only available for Express Checkout enabled Merchants. Refer to the [Express Checkout integration documentation](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/web-integration/#express-checkout) for more information. **getMasterpassButton(MasterpassButton.PAIRING_CHECKOUT_FLOW_ENABLED, masterpassCheckoutCallback)** When **PAIRING_CHECKOUT_FLOW_ENABLED** is passed as the value of behavior, then after clicking the Masterpass button the consumer will have to go through the checkout steps (selecting card and address) before seeing the pairing consent screen in the Masterpass wallet. This is called*pairing during checkout*. Note that the pairing process is NOT supported by all wallets on the Masterpass network, a Merchant should handle the case when no **pairingTransactionId** is returned #### 2. PAIRING_FLOW_ENABLED {#2-pairing_flow_enabled} This option is only available for Express Checkout enabled Merchants. Refer to the [Express Checkout integration documentation](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/web-integration/#express-checkout) for more information. **getMasterpassButton(MasterpassButton.PAIRING_FLOW_ENABLED, masterpassCheckoutCallback)** When **PAIRING_FLOW_ENABLED** is passed as the value of behavior, then after clicking the Masterpass button the consumer will see only the pairing consent screen in the Masterpass wallet. This is called *pairing outside of checkout.* ### Sample code: Merchant initialization {#sample-code-merchant-initialization} * Java ```Java public class MainActivity extends AppCompatActivity implements MasterpassInitCallback, MasterpassCheckoutCallback { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); MasterpassMerchantConfiguration sampleConfig = new MasterpassMerchantConfiguration.Builder() .setContext(this.getApplicationContext()) //context .setEnvironment(MasterpassMerchantConfiguration.SANDBOX) //environment .setLocale(new Locale("en","US")) //locale .setAnalyticsEnabled(false) //analytics on / off .setSignature(signature) // will be provided by Masterpass .setMerchantName("Merchant Name") .setExpressCheckoutEnabled(true)//if merchant is express enabled .setCheckoutId("448db128c17f4abe8eb497f9e73f2ff9") .build(); MasterpassMerchant.initialize(sampleConfig, this); } @Override public void onInitSuccess() { MasterpassButton masterpassButton = MasterpassMerchant.getMasterpassButton(this); this.addContentView(masterpassButton, new LinearLayout.LayoutParams( LinearLayout.LayoutParams.WRAP_CONTENT, LinearLayout.LayoutParams.WRAP_CONTENT)); } @Override public MasterpassCheckoutRequest getCheckoutRequest() { // note that Amount value is a long, so $9.99 should be given as 999 and $10 as 1000 for USD Amount total = new Amount(1000, Currency.getInstance(Locale.US).getCurrencyCode()); // $10.00 US ArrayList allowedNetworkTypes = new ArrayList<>(); allowedNetworkTypes.add(new NetworkType(NetworkType.MASTER)); Tokenization tokenization = getSampleTokenizationObject(); return new MasterpassCheckoutRequest.Builder() .setCheckoutId("448db128c17f4abe8eb497f9e73f2ff9") .setCartId("bb9410f9-e5a7-4f14-9c99-ea557d6fe2e8") .setAmount(total).setAllowedNetworkTypes(allowedNetworkTypes) .setTokenization(tokenization) // DSRP checkout is supported by Merchant .isShippingRequired(false) .build(); } @Override public void onCheckoutComplete(Bundle bundle) { String transactionId = bundle.getString(CheckoutResponseConstants.TRANSACTION_ID); Toast.makeText(this, "Here is the transaction ID:" + transactionId, Toast.LENGTH_SHORT).show(); } @Override public void onCheckoutError(MasterpassError masterpassError) { Toast.makeText(this, masterpassError.message(), Toast.LENGTH_SHORT).show(); } @Override public void onInitError(MasterpassError masterpassError) { Toast.makeText(this, masterpassError.message(), Toast.LENGTH_SHORT).show(); } @Override public MasterpassCheckoutRequest getUpdatedCheckoutData(List list, List list1, ShippingSummaryItem shippingSummaryItem, Address address, Amount amount) { // Only required if shipping is required return null; } private Tokenization getSampleTokenizationObject() { try { ArrayList format = new ArrayList<>(); CryptoOptions.Mastercard mastercard = new CryptoOptions.Mastercard(); CryptoOptions cryptoOptions = new CryptoOptions(); format.add("UCAF"); mastercard.setFormat(format); cryptoOptions.setMastercard(mastercard); String unpreditableNumber = Base64.encodeToString( Integer.toString(10000).getBytes("UTF-8"), Base64.NO_WRAP); return new Tokenization(unpreditableNumber, cryptoOptions); } catch (UnsupportedEncodingException e) { e.printStackTrace(); } return null; } } ``` ### Sample code: parsing CheckoutResponse bundle {#sample-code-parsing-checkoutresponse-bundle} Once a Masterpass transaction is successful, two possible values will be returned in the **onComplete()** method. Merchant applications should retrieve a transactionId and/or a **pairingTransactionId** and pass them to their own backend server. * Java ```Java public void onCheckoutComplete(Bundle checkoutResponseBundle) { String transactionId = checkoutResponseBundle.getString(CheckoutResponseConstants.TRANSACTION_ID); String pairingTransactionId = checkoutResponseBundle.getString(CheckoutResponseConstants.PAIRING_TRANSACTION_ID); } ``` ## Configure Payment Method {#configure-payment-method} ### Add a Masterpass Wallet as a Payment Method {#add-a-masterpass-wallet-as-a-payment-method} You can retrieve a PaymentMethod object in order to display a preferred Wallet and card for the consumer to checkout. When this method is invoked, the consumer will be able to select their preferred wallet. The selected wallet is returned to the Merchant; you can associate this wallet with the Merchant application for a future checkout. * Java ```Java MasterpassMerchant.addMasterpassPaymentMethod(new PaymentMethodCallback() { void onPaymentMethodAdded(MasterpassPaymentMethod masterpassPaymentMethod) { savePaymentMethod(masterpassPaymentMethod); } AddPaymentMethodRequest getPaymentMethodRequest(){ return new AddPaymentMethodRequest(getConfigCards(), "448db128c17f4abe8eb497f9e73f2ff9", "testUserID"); } void onFailure(MasterpassError masterpassError) { Toast.makeText(this, "Failed to add payment method" + masterpassError.message(), Toast.LENGTH_SHORT).show(); } }); ``` ### Checkout with Payment Method {#checkout-with-payment-method} Once a **PaymentMethod** is retrieved, it can then be used to checkout with a user-preferred wallet and card. Provide the **paymentMethodId** returned in the **PaymentMethod** to the checkout method as shown: * Java ```Java MasterpassMerchant.paymentMethodCheckout(paymentMethod.getPaymentWalletId, new MasterpassCheckoutCallback() { /** * Same implementation as other MasterpassCheckoutCallback implementations */ })); ``` ### Merchant library functionality {#merchant-library-functionality} The following functionality is provided by the Masterpass Merchant Android SDK (via the MasterpassMerchant class). 1. Invoke Masterpass programmatically without the Masterpass button (express checkout) 2. Reset the default wallet currently stored 3. Handle change wallet error These are described in more detail below. #### 1. Invoke Masterpass programmatically without the Masterpass button {#1-invoke-masterpass-programmatically-without-the-masterpass-button} Use **masterpassCheckout()** to invoke Masterpass programmatically. This will invoke Masterpass in the same behavior as with the 'no option' (no behavior specified) way of invoking getMasterpassButton(). * Java ```Java public class MainActivity extends AppCompatActivity implements MasterpassInitCallback, MasterpassCheckoutCallback{ @Override public void onInitSuccess() { MasterpassMerchant.masterpassCheckout(this); } // ... } ``` #### 2. Reset the default wallet currently stored {#2-reset-the-default-wallet-currently-stored} If a merchant app has invoked Masterpass by calling **getMasterpassButton()** or **masterpassCheckout()**, then the SDK may have remembered the user's last-used wallet. The merchant app may use this method to force reset the currently stored last-used Masterpass-enabled wallet information. * Java ```Java MasterpassMerchant.resetDefaultWallet(); ``` #### 3. Handle change wallet error {#3-handle-change-wallet-error} If a merchant app did not invoke Masterpass with the default integration via **getMasterpassButton()** , then the merchant app must handle the error code **MasterpassError.ERROR_CODE_CHANGE_WALLET_SELECTED** appropriately. * If this error code is received when invoking Masterpass through **masterpassCheckout()** , then the merchant app should call **resetDefaultWallet()** and call **masterpassCheckout()** again. * Java ```Java @Override public void onCheckoutError(MasterpassError masterpassError) { // ... if (masterpassError.equals(MasterpassError.ERROR_CODE_CHANGE_WALLET_SELECTED)) { MasterpassMerchant.resetDefaultWallet(); MasterpassMerchant.masterpassCheckout(true, this); }; } ``` ## Testing {#testing} You can test completing a transaction via one of the Masterpass wallets on the web by setting the environment to SANDBOX during initialization. ## Appendix {#appendix} ### MasterpassCheckoutRequest object details {#masterpasscheckoutrequest-object-details} The following table lists the field details for the MasterpassCheckoutRequest object. | **Field** | **Description** | |--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MasterpassCheckoutRequest.Amount | Contains the amount of the transaction and the currency code.**Data Type:** Amount object**Required:** Yes | | MasterpassCheckoutRequest.CheckoutId | An ID provided to a merchant during onboarding. **Data Type:** String **Required:** Yes | | MasterpassCheckoutRequest.CartId | An ID provided by a merchant to Masterpass to indicate a unique transaction. **Data Type:** String **Required:** Yes | | MasterpassCheckoutRequest.AllowedNetworkTypes | Contains a list of Payment Networks supported by the merchant **Data Type:** List of NetworkType object **Required:** Yes | | MasterpassCheckoutRequest.AmountPending | DEPRECATEDIndiates if the amount is pending. The wallet may display the MasterpassCheckoutRequest.Amount field differently. **Data Type:** Boolean **Required:** No | | MasterpassCheckoutRequest.ShippingRequired | Indicates if this transaction requires Shipping or not. If false, the wallet will not display any shipping addresses for the user to select. **Data Type:** Boolean **Required:** No | | MasterpassCheckoutRequest.Tokenization | Contains the parameters to indicate this merchant's support for tokenized card details **Data Type:** Tokenization object **Required:** No | | MasterpassCheckoutRequest.MerchantUserId | An ID provided by a merchant to Masterpass for express checkout pairing purpose. **Data Type:** String **Required:** No | | MasterpassCheckoutRequest.MerchantName | The display name of a merchant. **Data Type:** String **Required:** No | | MasterpassCheckoutRequest.CheckoutSummaryItems | Contains a list of CheckoutSummaryItems to be displayed. **Data Type:** List of CheckoutSummaryItems object **Required:** No | | MasterpassCheckoutRequest.ShippingSummaryItems | Contains a list of ShippingSummaryItems to be displayed. **Data Type:** List of ShippingSummaryItems object **Required:** No | | Amount | | | Amount.Total | An amount value to be displayed. This value is in minor units for the specific currency so a value of 999 = $9.99 if the currency is USD **Data Type:** Long **Required:** Yes | | Amount.CurrencyCode | Contains the ISO 4217 currency code of a currency. **Data Type:** String **Required:** Yes | | CheckoutSummaryItem - only supported in App-to-App. This is not available in the merchant embedded native experience or App-to-Web | | | CheckoutSummaryItem.Label | A title of the CheckoutSummaryItem to be displayed, for example, "tax". **Data Type:** String **Required:** Yes | | CheckoutSummaryItem.Amount | Contains an amount of the CheckoutSummaryItem to be displayed. **Data Type:** Amount Object **Required:** Yes | | ShippingSummaryItem - - only supported in App-to-App. This is not available in the merchant embedded native experience or App-to-Web | | | ShippingSummaryItem.Label | A title of the ShippingSummaryItem to be displayed, for example, "2-day shipping". **Data Type:** String **Required:** Yes | | ShippingSummaryItem.Amount | Contains an amount of the CheckoutSummaryItem to be displayed. \*\*Data Type:\*\*Amount object **Required:** Yes | | NetworkType | | | NetworkType.NetworkType | A PaymentNetwork, for example, "MASTER", "VISA", "AMEX", "DISCOVER", "DINERS". **Data Type:** String **Required:** Yes | | Tokenization | | | Tokenization.CryptoOptions | Contains the parameters to indicate a merchant's support of tokenized Mastercard or Visa card details. **Data Type:** CryptoOption object **Required:** Yes | | Tokenization.UnpredictableNumber | Random number, generated by the merchant, for use generating the DSRP cryptogram. **Data Type:** String **Required:** Yes | | CryptoOptions | | | CryptoOptions.Mastercard | Contains the parameters to indicate which type of tokenized Mastercard card details a merchant partner supports. **Data Type:** Mastercard object **Required:** Yes | | CryptoOptions.Mastercard.Format | Contains the cryptogram types that a merchant partner supports for tokenized Mastercard card details, for example, "UCAF" and "ICC". A merchant partner should reach out its Mastercard account manager or work with its payment processor to determine which format to support. **Data Type:** List **Required:** Yes | | CryptoOption.Visa | Contains the parameters to indicate which type of tokenized Visa card details a merchant supports. **Data Type:** Mastercard object **Required:** Yes | | CryptoOptions.Visa.Format | Contains the cryptogram types that a merchant partner supports for tokenized Visa card details e.g. TAVV. A merchant should reach out its Mastercard account manager or work with its payment processor to determine which format to support. **Data Type:** List **Required:** Yes | For more information about tokenization, see the [Masterpass DSRP and Tokenization](https://developer.mastercard.com/masterpass-merchant-onboarding/documentation/masterpass-dsrp-and-tokenization/) guide. ### Error code details {#error-code-details} The following errors may be returned from **onCheckoutError()** or **onInitError()** . | Error | Description | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | ERROR_CODE_INITIALIZATION_FAILED | This error is returned when SDK initialization failed to retrieve necessary configuration files from Masterpass. | | ERROR_WEB_CHECKOUT_NOT_ENABLED | This error is returned when invoking Masterpass via getMasterpassButton() or MasterpassCheckout() without enabling web checkout. | | ERROR_PACKAGE_NOT_FOUND | This error is returned when invoking Masterpass via specificWalletCheckout() and the package name requested is not available. | | ERROR_CODE_CANCEL_WALLET | This error is returned when a user decides to cancel a transaction via Masterpass. | | ERROR_WEB_BROWSER_NOT_FOUND | This error is returned when a merchant partner enables completing a Masterpass transaction on the web and no available browsers are found on the device. |