# Masterpass Checkout Android SDK - v2.8 source: https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-checkout-android-sdk-v28/index.md This page contains details of the latest version of the Masterpass Checkout Android SDK, version 2.8 Note: Merchants in the US wishing to begin work on adding support for Click to Pay to their mobile applications should see the[Mastercard Click to Pay and Masterpass Checkout Android SDK](https://github.com/Mastercard/commerce-web-android#overview) which provides backward compatibility with Masterpass v7. ## 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_v282.zip](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/uploads/masterpass-merchant-android-sdk-v282.zip) | Masterpass SDK library:- masterpass-merchant-2.8.2.aarSample application Source code project for sample application. Last Updated: June 14th 2019 | Note that in previous releases we provided three separate libraries (masterpass-core.aar, masterpass-merchant.aar and devicelevelauthentication.aar). These are all now combined in one single library, "masterpass-merchant-.2.8.x.aar". ## What's new in this release? {#whats-new-in-this-release} The following changes and new features in version 2.8.x of the Masterpass Checkout Android SDK, compared to version 2.7: Version 2.8.2 provides: * Minor bug fixes and enhancements. Version 2.8.1 provided a fix for the following: * Fix crash when performing web checkout and switching between browser and application. ### Previous releases {#previous-releases} * [Masterpass Checkout Android SDK v2.7](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v27/index.md) * [Masterpass Checkout Android SDK v2.6](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v26/index.md) * [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} There are no migration notes for this release. 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 { implementation "com.mastercard.mp.checkout:masterpass-merchant:2.8.1@aar" implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version" implementation "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version" } ``` 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(...); } # if the merchant app has included the card.io dependency then the following additional proguard rules need to be added: -keep class io.card.** -keepclassmembers class io.card.** { *; # if the merchant app has not included the card.io dependency then the following additional proguard rule needs to be added: -dontwarn class io.card.** ``` ### 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 documentation](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/backend-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 documentation](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/backend-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 .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) .setMerchantName("Merchant Name") .setTokenization(tokenization) // DSRP checkout is supported by Merchant .setAllowedNetworkTypes(allowedNetworkTypes) .setSuppress3Ds(false) .setShippingProfileId("5886541") .setCallBackUrl("http://masterpass.com") .isShippingRequired(false) .setCvc2Support(false) .setValidityPeriodMinutes(0) .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(); } 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 Masterpass Merchant Android SDK (via the MasterpassMerchant class) provides the ability to invoke Masterpass programmatically without the Masterpass button (express checkout) using **masterpassCheckout().** * Java ```Java public class MainActivity extends AppCompatActivity implements MasterpassInitCallback, MasterpassCheckoutCallback{ @Override public void onInitSuccess() { MasterpassMerchant.masterpassCheckout(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.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.suppress3DS | Whether a merchant needs to suppress 3DS for checkout **Data Type** : Boolean **Required**: No | | MasterpassCheckoutRequest.shippingProfileId | Identifier representing the merchant's supported shipping countries and/or subdivisions **Data Type:** String **Required**: No | | MasterpassCheckoutRequest.callbackUrl | The callbackUrl for the merchant if it its different to the one configured through the merchant portal **Data Type** : Boolean **Required**: No | | MasterpassCheckoutRequest.cvc2support | Whether a merchant supports a dynamic cvc code used for Dynamic Token Verification: **Data Type** : Boolean **Required**: No | | MasterpassCheckoutRequest.validityPeriodMinutes | Validity period for DTV code in minutes (also known as UCAF Bypass) **Data Type** : Integer **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 | | 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_CODE_INITIALIZATION_FAILED_CANNOT_RETRIEVE_WALLETS | This error code is returned if the SDK initialization web request for fetching merchant and country configurations failed. | | 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. | | ERROR_CODE_REQUEST_TIMEOUT | This error is returned when any Web Service API of MEX SDK time out. | | ERROR_CODE_REQUEST_FAILED | This error is returned when any Web Service API of MEX SDK failed with an exception. | | ERROR_CODE_WALLET_CERTIFICATE_RETRIEVE_FAILED | This error is returned when the fetch public key certificate service failed (for preparing encryption key). | | ERROR_CODE_PAYMENT_METHODS_NOT_AVAILABLE | This error is returned when there is no payment method either Merchant Embedded Checkout or Web Checkout available for merchant country. | | ERROR_MEX_CHECKOUT_NOT_AVAILABLE | This error is returned when there is no merchant embedded checkout available during express pairing or Masterpass checkout or Masterpass button checkout. | | ERROR_GET_LEGAL_DOCS_INFO_FAILED | This error is returned when fetch legal doc version for merchant country service failed. |