- Overview
- Configuration on Merchant Portal
- Installation
- Configuration
- Checkout Button
- Transaction Result
- Migrating from masterpass-merchant
commerce-web
is a lightweight library used to integrate Merchants with
EMV Secure Remote Commerce
and Mastercard's web-based SRC-Initiator with backward compatibility for existing Masterpass
integrations. commerce-web
facilitates the initiation of the checkout experience and returns the transaction result to the
Merchant after completion.
It is very important to configure these values properly on the portal. If these values are not configured in proper format, merchant application will not be able to do successful checkout.
callbackUrl
must be configured with an Intent
URI. Below is an example format of callbackUrl
for a sample merchant application named FancyShop
Example format of callbackUrl
: intent: //commerce/#Intent;scheme=fancyshop;package=com.mastercard.fancyshop;endChannel
: Android
Please use AndroidX version of our SDK only when your Application uses AndroidX library. For Applications running android support library (API Level 28 and below), we recommend using our support library version instead.
For AndroidX version of our SDK, include the following in build.gradle
:
dependencies {
implementation 'com.mastercard.commerce:commerce-web:1.0.8'
}
For Applications using Android support library (API level 28 and below), include the following
in build.gradle
:
dependencies {
implementation 'com.mastercard.commerce:commerce-web:1.0.7'
}
When initializing CommerceWebSdk
, a CommerceConfig
and Context
object need to be provided.
CommerceConfig
requires the following parameters:
locale
: This is the locale in which the transaction is processingcheckoutId
: The unique identifier assigned to the merchant during onboardingcheckoutUrl
: The URL used to load the checkout experience. Note: when testing in the Sandbox environment, usehttps://sandbox.src.mastercard.com/srci/
. For Production, usehttps://src.mastercard.com/srci/
allowedCardTypes
: The payment networks supported by this merchant (e.g. master, visa, amex, discover, maestro, diner). Currently SRC supports only four cards: master, visa, amex and discover.
Below is a sample code snippet to initialize Sdk for Sandbox environment :
Locale locale=Locale.US;
String checkoutId="1d45705100044e14b52e71730e71cc5a";
String checkoutUrl="https://sandbox.src.mastercard.com/srci/";
Set<CardType> allowedCardTypes=new HashSet<>();
allowedCardTypes.add(CardType.MASTER);
allowedCardTypes.add(CardType.VISA);
allowedCardTypes.add(CardType.AMEX);
CommerceConfig commerceConfig=new CommerceConfig(locale,checkoutId,checkoutUrl,allowedCardTypes);
Merchant App can Optionally provide a different image to Click2Pay (Checkout) Button.
Merchant App Module must have the button images on drawable folders: hdpi, mdpi, xhdpi, xxhdpi etc
before calling the setCheckoutButtonImage() method on CommerceConfig
object.
//Optional - Add the below two lines only if Merchant wants a different image on Checkout button.
Drawable buttonImage=context.getResources().getDrawable(R.drawable.merchant_button);
commerceConfig.setCheckoutButtonImage(buttonImage);
Initialize CommerceWebSdk
CommerceWebSdk.getInstance().initialize(commerceConfig,context);
Transactions are initiated using the CheckoutButton
object. Below is a method to get the CheckoutButton
object.
//CommerceWebSdk.java
public CheckoutButton getCheckoutButton(final CheckoutCallback checkoutCallback);
Add this to your layout with LayoutParams.WRAP_CONTENT
for width
and height
.
CheckoutCallback
is an interface in the SDK, designed to receive CheckoutRequest
from the
merchant. CheckoutRequest is required from the merchant in order to initiate the checkout
experience. Below is the method of CheckoutCallback interface, where SDK requests for
CheckoutRequest object via CheckoutRequestListener
.
//CheckoutCallback.java
void getCheckoutRequest(CheckoutRequestListener listener);
CheckoutRequestListener
is a Listener interface to set the CheckoutRequest
. Below is a method to
set the CheckoutRequest.
//CheckoutCallback.java
void setRequest(CheckoutRequest request);
Here is the sample code snippet to get CheckoutButton
object, using getCheckoutRequest
method of
CheckoutCallback, by setting the CheckoutRequest via setRequest
method of CheckoutRequestListener:
CommerceWebSdk.getInstance().getCheckoutButton(new CheckoutCallback(){
@Override public void getCheckoutRequest(CheckoutRequestListener listener){
listener.setRequest(getSrcCheckoutRequest());
}
}));
The implementation of the checkout can be like this:
private CheckoutRequest getSrcCheckoutRequest(){
Set<Mastercard.MastercardFormat>mastercardFormatSet=new HashSet<>();
mastercardFormatSet.add(Mastercard.MastercardFormat.ICC);
mastercardFormatSet.add(Mastercard.MastercardFormat.UCAF);
CryptoOptions mastercard=new Mastercard(mastercardFormatSet);
Set<CryptoOptions> cryptoOptionsSet=new HashSet<>();
cryptoOptionsSet.add(mastercard);
CheckoutRequest request=new CheckoutRequest.Builder()
.amount(totalAmount)
.cartId(UUID.randomUUID().toString())
.currency("USD")
.cryptoOptions(cryptoOptionsSet)
.suppressShippingAddress(isShippingRequired())
.build();
return request;
}
checkoutRequest
: Data object with transaction-specific parameters needed to complete checkout.
This request can also override existing merchant configurations.
Here are the required and optional fields:
Parameter | Type | Required | Description |
---|---|---|---|
amount | Double | Yes | The transaction total to be authorized |
cartId | String | Yes | Randomly generated UUID used as a transaction id |
currency | String | Yes | Currency of the transaction |
callbackUrl | String | No | URL used to communicate back to the merchant application |
cryptoOptions | Set<CryptoOptions> | No | Cryptogram formats accepted by this merchant |
cvc2Support | Boolean | No | Enable or disable support for CVC2 card security |
shippingLocationProfile | String | No | Shipping locations available for this merchant |
suppress3Ds | Boolean | No | Enable or disable 3DS verification |
suppressShippingAddress | Boolean | No | Enable or disable shipping options. Typically for digital goods or services, this will be set to true |
unpredictableNumber | String | No | For tokenized transactions, unpredictableNumber is required for cryptogram generation |
validityPeriodMinutes | Integer | No | The expiration time of a generated cryptogram, in minutes |
Once the checkout is complete, the result of transaction is returned to the application via
an Intent
containing the transactionId
. In order to receive the result, the application must
declare an intent-filter
in the merchant application.
This intent filter is declared in AndroidManifest.xml
for the Activity
receiving the Intent
.
As mentioned in Configuration on Merchant Portal section above, if the callbackUrl
is configured
like intent://commerce/#Intent;scheme=fancyshop;package=com.mastercard.fancyshop;end
, then value
of android:host
will be commerce
and value of android:scheme
will be fancyshop
. Following is
an example:
<activity android:name=".CheckoutActivity">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<data android:host="commerce" android:path="/" android:scheme="fancyshop" />
</intent-filter>
</activity>
In CheckoutActivity
you would override onCreate()
to parse the Intent for the transaction data.
The activity is started with the Intent.FLAG_ACTIVITY_CLEAR_TOP
flag.
When the Intent
is received, the transactionId
is returned by
the stringExtra
CommerceWebSdk.COMMERCE_TRANSACTION_ID
Intent intent=getIntent();
String transactionId=intent.getStringExtra(CommerceWebSdk.COMMERCE_TRANSACTION_ID);
//complete transaction
Please update the configurations on merchant portal as specified
in Configuration on Merchant Portal
section.
Note: masterpass-merchant
APIs are deprecated in commerce-web
and will be removed in
subsequent versions. It is encouraged to migrate to the APIs above.
commerce-web
provides API compatibility for masterpass-merchant:2.8.x
. Existing applications
using masterpass-merchant
can easily migrate to commerce-web
with minimal changes. Consider the
following when migrating from masterpass-merchant
to commerce-web
.
All classes and interfaces used with masterpass-merchant
are packaged with commerce-web
. This
means that when switching to
commerce-web
, existing class imports can remain unchanged. There are changes to the functionality
of some APIs in order to support future payment platforms.
MasterpassMerchantConfiguration
has 2 new required fields
allowedNetworkTypes
: The payment networks supported by this merchant (e.g.master
,visa
,amex
). Note: this is moved fromMasterpassCheckoutRequest
checkoutUrl
: The URL used to load the checkout experience. This parameter replacesenvironment
frommasterpass-merchant
.
Environment | URL |
---|---|
Masterpass Sandbox | https://sandbox.src.mastercard.com/srci/ |
Masterpass Production | https://src.mastercard.com/srci/ |
integration here**
Note: this method is deprecated
//MasterpassMerchant.java
public static void addMasterpassPaymentMethod(PaymentMethodCallback paymentMethodCallback);
For commerce-web
, this method provides a single
MasterpassPaymentMethod
object which can be displayed and used for paymentMethodCheckout()
. It
is configured with the following fields
paymentMethodLogo
The masterpass logo asBitmap
pairingTransactionId
: ""paymentMethodLastFourDigits
: ""
Note: this method is deprecated
//MasterpassMerchant.java
public static void paymentMethodCheckout(String paymentMethodId,
MasterpassCheckoutCallback masterpassCheckoutCallback);
paymentMethodCheckout()
initiates the standard checkout flow using
masterpassCheckoutCallback.getCheckoutRequest()
.
Note: this method is deprecated
//MasterpassMerchant.java
public static void pairing(boolean isCheckoutWithPairingEnabled,MasterpassCheckoutCallback masterpassCheckoutCallback);
pairing(isCheckoutWithPairingEnabled, callback)
initiates the standard checkout flow
if isCheckoutWithPairingEnabled
is true
.
Otherwise, checkoutCallback.onCheckoutError(MasterpassError)
is called
with MasterpassError.ERROR_CODE_NOT_SUPPORTED
.