# Masterpass Checkout Android SDK v2.0 source: https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v2/index.md \*\*This page contains details of the 2.0 release (2017 R7) of the SDK. For details of the latest release, see [here](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/previous-releases/masterpass-checkout-android-sdk-v25/index.md). ## Overview {#overview} The Masterpass Checkout Android SDK enables Masterpass merchant partners to add Masterpass to their Android apps. Merchant partners can invoke Masterpass in one of two ways using the SDK. With the default integration, Masterpass is invoked using the Masterpass Button, but merchant partners can also invoke Masterpass programmatically. Note: Express Checkout is not supported in the US and Canada. Please contact your regional representative for more information. ## Onboarding {#onboarding} To complete onboarding for the Masterpass Checkout Android SDK, merchant partners must complete the following steps. 1. Complete the standard Masterpass onboarding steps. 2. To support completing a Masterpass transaction via one of the Masterpass wallets on the web, add a callback URL to your Masterpass project on [Mastercard Developers](https://developer.mastercard.com/) 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 red indicates the package name of your Android app. ## SDK Download {#sdk-download} | ZIP File | Contents | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [masterpass-merchant-android-sdk.zip](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/uploads/masterpass-merchant-android-sdk.zip) | - AAR Files- Sample application- Version: 2.0.0- Last updated: Mar 2017 | ## Integration - Invoking Masterpass using the Masterpass Button {#integration---invoking-masterpass-using-the-masterpass-button} Complete the following steps to invoke Masterpass checkout using the Masterpass Button. ### 1. Add the SDK to your application {#1-add-the-sdk-to-your-application} Download the ZIP file, and add the AAR files to your app's **/libs** folder. Add the following to your application's **Build.gradle** file. * Java ```Java repositories { flatDir { dirs 'libs' } } dependencies { // The SDK needs the following dependencies compile 'com.android.support:appcompat-v7:26.+' compile 'com.android.support:recyclerview-v7:26.+' compile 'com.android.support:customtabs:26.+' compile 'com.mastercard.mp.checkout:masterpass-core:2.0.0@aar' compile 'com.mastercard.mp.checkout:masterpass-merchant:2.0.0@aar' } ``` ### 2. Initialize the SDK and get the MasterpassButton object {#2-initialize-the-sdk-and-get-the-masterpassbutton-object} * If the **WEB_FLOW_ENABLED** option is indicated: * The consumer will complete a Masterpass transaction via one of the Masterpass wallets on the web. * If the **PAIRING_CHECKOUT_FLOW_ENABLED** option is indicated: * **Use this option only if the Masterpass Express Checkout flow is enabled for your merchant account.** * The consumer can complete a Masterpass transaction and pairing process via one of the Masterpass wallets on the web. * **NOTE:** The pairing process is not supported by all wallets on the Masterpass network. You must handle cases when no **pairingTransactionId** is returned. * If the **PAIRING_FLOW_ENABLED** option is indicated: * **Use this option if the Masterpass Express Checkout flow is enabled for your merchant account.** * The consumer can complete a Masterpass pairing process via one of the Masterpass wallets on the web. * **NOTE:** That the pairing process is not supported by all wallets on the Masterpass network. You must handle cases when no **pairingTransactionId** is returned. The **getMasterpassButton()** can also be called without any options. However, such implementation is deprecated and should not be used. Please use one of the 3 options above. * Java ```Java public class MainActivity extends AppCompatActivity implements MasterpassInitCallback, MasterpassCheckoutCallback{ @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); String signature = ""; // will be provided by Masterpass 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 .build(); MasterpassMerchant.initialize(sampleConfig, this); } @Override public void onInitSuccess() { MasterpassButton masterpassButton = MasterpassMerchant.getMasterpassButton(MasterpassButton.WEB_FLOW_ENABLED, this); this.addContentView(masterpassButton, new LinearLayout.LayoutParams(LinearLayout.LayoutParams.WRAP_CONTENT, LinearLayout.LayoutParams.WRAP_CONTENT)); } @Override public MasterpassCheckoutRequest getCheckoutRequest() { Amount total = new Amount(1000, Currency.getInstance(Locale.US).getCurrencyCode()); ArrayList allowedNetworkTypes = new ArrayList<>(); allowedNetworkTypes.add(new NetworkType(NetworkType.MASTER)); return new MasterpassCheckoutRequest.Builder() .setCheckoutId("448db128c17f4abe8eb497f9e73f2ff9").setCartId("42423sf4") .setAmount(total).setAllowedNetworkTypes(allowedNetworkTypes) .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; } } ``` ### 3. Parse the CheckoutResponse bundle {#3-parse-the-checkoutresponse-bundle} Once a Masterpass transaction is successful, two possible values are returned in the **onComplete()** method. You should retrieve **transactionId** and/or **pairingTransactionId** and pass them to your back end server. For instructions on how to fetch payment data using these IDs, see the [Masterpass Merchant Integration API Reference](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/api-reference/index.md). * Java ```Java public void onComplete(Bundle checkoutResponseBundle) { String transactionId = checkoutResponseBundle.getString(CheckoutResponseConstants.TRANSACTION_ID); // optional, pairing transaction id only applies in case of Pairing String pairingTransactionId = checkoutResponseBundle.getString(CheckoutResponseConstants.PAIRING_TRANSACTION_ID); // Once you have the transactionId or pairingTransactionId, you can pass them to your server and call Masterpass to fetch checkout resources } ``` ## Integration - Invoking Masterpass programmatically {#integration---invoking-masterpass-programmatically} See below on how to invoke Masterpass checkout programmatically. ### Invoke Masterpass programmatically without the Masterpass button {#invoke-masterpass-programmatically-without-the-masterpass-button} Use the **webCheckout()** method to invoke Masterpass programmatically without the Masterpass Button. * Java ```Java public class MainActivity extends AppCompatActivity implements MasterpassInitCallback, MasterpassCheckoutCallback{ @Override public void onInitSuccess() { MasterpassMerchant.webCheckout(this); } // ... } ``` ## Appendix {#appendix} ### MasterpassCheckoutRequest object details {#masterpasscheckoutrequest-object-details} The following table lists the field details for the MasterpassCheckoutRequest object. | Field | Description | |-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | MasterpassCheckoutRequest | | | MasterpassCheckoutRequest.Amount | Contains the amount of the transaction and the currency code **Data Type:** Amount object **Required:** Yes | | MasterpassCheckoutRequest.CheckoutId | ID provided to the merchant partner during onboarding **Data Type:** String **Required:** Yes | | MasterpassCheckoutRequest.CartId | ID provided by the merchant partner to Masterpass to indicate a unique transaction **Data Type:** String **Required:** Yes | | MasterpassCheckoutRequest.AllowedNetworkTypes | List of payment networks supported by the merchant partner **Data Type:** List of NetworkType object **Required:** Yes | | MasterpassCheckoutRequest.MerchantUserId | An ID provided by the merchant partner to Masterpass for express checkout pairing purpose. **Data Type:** String **Required:** No | | MasterpassCheckoutRequest.ShippingRequired | Indicates whether the transaction requires shipping; if false, the wallet will not display shipping addresses for the user to select **Data Type:** Boolean **Required:** No | | Amount | | | Amount.Total | Amount to be displayed to the consumer. The amount is in minor units e.g. 999 = $ 9.99 for USD currency **Data Type:** long **Required:** Yes | | Amount.CurrencyCode | The ISO 4217 currency code of the currency **Data Type:** String **Required:** Yes | | NetworkType | | | NetworkType.NetworkType | PaymentNetwork (e.g., "MASTER", "VISA", "AMEX", "DISCOVER", "DINERS") **Data Type:** String **Required:** Yes | ### Error Code Details {#error-code-details} The following errors may be returned from **onCheckoutError()** or **onInitError()** . | Error | Description | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ERROR_CODE_INITIALIZATION_FAILED | Returned when SDK initialization failed to retrieve necessary configuration files from Masterpass | | ERROR_WEB_CHECKOUT_NOT_ENABLED | Returned when invoking Masterpass via getMasterpassButton() or MasterpassCheckout() without enabling web checkout and no Masterpass-enabled Wallet Apps are installed on the device. | | ERROR_CODE_CANCEL_WALLET | Returned when a user decides to cancel a transaction via Masterpass. | | ERROR_WEB_BROWSER_NOT_FOUND | Returned when a merchant partner enables completing a Masterpass transaction on the web and no available browsers are found on the device. | ## Testing {#testing} You can test completing a transaction via one of the Masterpass wallets on the web by setting the testing environment to SANDBOX during initialization.