Masterpass Android SDK

Android integration

Portmone SDK supports Android 4.4 KitKat version, API level 19 and above.

Opportunities provided by Portmone SDK

Masterpass wallet:

• add cards to an existing wallet or create a new one;
• delete cards from an existing wallet;
• get a list of cards for an existing wallet.

Payment:

• adding funds to a mobile phone account using Masterpass cards;
• paying for services by personal account using Masterpass cards.

Before getting started

Sign up at Masterpass™

To get started with Masterpass™, you need to go through the merchant registration process at developers.mastercard.com. To do this:

1. Go to https://developer.mastercard.com/account/sign-up
2. Complete the registration form and then go through the e-mail confirmation procedure
3. Create project on the page https://developer.mastercard.com/dashboard → Create new project

Sign up at Portmone.com

After receiving the keys from Masterpass™, send the following information to the Portmone.com:

• the keys data from your personal account, namely:
  • Public key (Press “Actions” → “Download *.pem”)
  • Keystore password
  • Key alias

You can find these data in the Key Management section at https://developer.mastercard.com/masterpass/merchant/#/keyManagement2

• Masterpass™ Checkout ID (copy from the next page in your personal account: https://developer.mastercard.com/masterpass/merchant/#/checkoutCredentials)

You should send the information via email at [email protected] with the subject “Partner [Your company's name] Onboarding”. Please make sure that you have permanent access to the mailbox from which you will send this email and that the mailbox is registered with your company's trusted domain. Emails from free public domains (gmail.com, yahoo.com, ukr.net etc.) will be automatically filtered out.

After registering your Masterpass™ Merchant data in the Portmone.com system, you will be contacted to assist on further integration and testing steps and will be provided the following information:

• Portmone.com Merchant Id
• Portmone.com Merchant Login
• The current version of the Android SDK along with the sample of application that uses SDK.

1. AAR integration

Add portmone-v1.0.aar file to the libs folder.

build.gradle (project level)

allprojects {
   repositories {
       google()
       jcenter()
       flatDir {
           dirs 'libs'
       }
   }
}

build.gradle (app level)

dependencies {
       implementation(name:'portmone-v1.0', ext:'aar')

       implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
       implementation 'io.reactivex.rxjava2:rxjava:2.2.4'
       implementation 'com.squareup.retrofit2:retrofit:2.4.0'
       implementation 'com.squareup.retrofit2:converter-gson:2.4.0'
       implementation "com.squareup.retrofit2:adapter-rxjava2:2.4.0"
       implementation 'com.googlecode.libphonenumber:libphonenumber:8.9.7'
}

2. Get started with the SDK

To use the SDK methods, before you get started you need to call a method which accepts a set of required parameters to work with SDK :

PortmoneSDK.init(Context, InitParams);

InitParams object

Field	Type	Description	Nullability
clientId	String	A unique identifier of the client in the Masterpass system	Nonnull
merchantKey	String	Unique key	Nonnull

3. Authorization (AuthService)

To use SDK features you should log in to the system. AuthService, which is obtained using PortmoneSDK.getAuthService(), and its authorize method are used for authorization. Authorization for one user is stored during the life of the application after calling the method. To change the user you need to call this method again with other parameters.

During the method call, the wallet status is checked using the specified phone number. If necessary, the client is automatically linked to the Masterpass system. In this case, card verification with the OTP code is necessary and error 2113 appears.

AuthService

void authorize(
        String phoneNumber,
        String userId,
        LoginListener loginListener
  );

authorize method parameters

Parameter	Type	Description	Example
phoneNumber	String	User mobile phone number. Used as an identifier in the Masterpass wallet.	“380666789555”
userId	String	User ID in the Portmone system. Required for identification in the Portmone system.	“3715100”
loginListener	LoginListener	Asynchronous callback with the result of authorization.

Getting authorization result:

LoginListener

void onSuccess();

void onError(Throwable throwable);

LoginListener methods

Method	Parameters	Description
onSuccess		Called after successful authorization in the system.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object. When checking the status of a wallet, an error 2113 may occur, which requires OTP verification of the card.

Example:

final AuthService authService = PortmoneSDK.getAuthService();

authService.authorize(
    "380666789555",
     "3714123",
     new LoginListener() {

  @Override
  public void onSuccess() {
     // authorization success
  }

  @Override
  public void onError(final Throwable throwable) {
     // error occurred
     throwable.printStackTrace();
  }

4. Masterpass wallet (CardService)

The CardService is used to work with the wallet. The object can be obtained using the PortmoneSDK.getCardService(). The service provides possibility to add or remove cards and get a list of cards in the existing wallet.

CardService

void getMasterpassCards(GetCardsListener getCardsListener);

void addMasterpassCard(
     MasterPassEditText cardNumber,
     int expireMonth,
     int expireYear,
     String cardName,
     MasterPassEditText cvv,
     CheckBox termsCondition,
     AddCardListener addCardListener
);

void deleteMasterpassCard(String cardName, DeleteCardListener listener);

4.1 Adding a card (addMasterpassCard)

The method adds a card to an existing Masterpass wallet using the phone number specified in AuthService#authorize or creates a new wallet if this number is not found.

addMasterpassCard method parameters

Parameter	Type	Description	Example
cardNumber	MasterPassEditText	The card number filled in the MasterpassEditText object. The following parameters should be specified xmlns:masterpass= "http://schemas.android.com/apk/res-auto" аndroid:inputType="number" android:digits="01234 56789" android:maxLength="19" masterpass:type="1" The methods getText() and setText() are not allowed. Their call leads to an error.	See below
expireMonth	int	Card expiration month	12
expireYear	int	Card expiration year	2020 or 20
cardName	String	A unique card name in the wallet	“Card Name”
cvv	MasterpassEditText	The card security code (CVV2/CVC2) filled in the MasterpassEditText object. The following parameters should be specified xmlns:masterpass= "http://schemas.android.com/apk/res-auto" аndroid:inputType="number" android:maxLength="4" masterpass:type="3" The methods getText() and setText() are not allowed. Their call leads to an error.	See below
termsConditions	CheckBox	Confirmation of the Masterpass rules acceptance
addCardListener	AddCardListener	Asynchronous callback for adding a card

Example of the cardNumber parameter:

<cardtek.masterpass.attributes.MasterPassEditText
android:id="@+id/number"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:hint="Card Number"
android:inputType="number"
android:digits="01234 56789"
android:maxLength="19"
masterpass:type="1"/>

Example of the cvv parameter:

<cardtek.masterpass.attributes.MasterPassEditText
android:id="@+id/cvc"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:hint="cvv"
android:inputType="number"
android:maxLength="4"
masterpass:type="3"/>

Obtaining the result of adding a card:

AddCardListener

void onSuccess();

void onError(Throwable throwable);

AddCardListener methods

Method	Parameters	Description
onSuccess		Called after a card is added successfully.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object. When adding a card, errors 2113, 2114 may occur, which requires OTP verification of the card and phone number.

Example:

public class AddCardActivity extends AppCompatActivity {

   EditText etxtCardName;
   MasterPassEditText cardNumber;
   Spinner spMonth;
   Spinner spYear;
   MasterPassEditText cvv;
   CheckBox cbTerms;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_add_card);
     etxtCardName = findViewById(R.id.etxt_card_name);
     cardNumber = findViewById(R.id.mpetxt_card_number);
     cvv = findViewById(R.id.mpetxt_cvv);
     spMonth = findViewById(R.id.expMonth);
     spYear = findViewById(R.id.expYear);
     cbTerms = findViewById(R.id.cb_terms);
  }

  public void addCard() {
      cardService = PortmoneSDK.getCardService();
      cardService.addMasterpassCard(
                 cardNumber,
                 Integer.valueOf(spMonth.getSelectedItem().toString()),
                 Integer.valueOf(spYear.getSelectedItem().toString()),
                 etxtCardName.getText().toString(),
                 cvv,
                 cbTerms,
                 new AddCardListener() {

                    @Override
                    public void onSuccess() {
                       //add card success
                    }

                    @Override
                    public void onError(final Throwable throwable) {
                       // error occurred
                    }
                 }
           );
}

For MasterpassEditText with a card number it is possible to specify a CardTypeCallback. It gives possibility to get information about the entered card number for its identification. Specified using the MasterpasEditText#setCardTypeCallback method.

CardTypeCallback

 void getFirstChar(char firstChar)

 void getFirst6Chars(String digits)

 void cancelInstallment()

CardTypeCallback methods

Method	Parameters	Description
getFirstChar	firstChar:char	Called when entering first character of a card number and returns it as a parameter.
getFirst6Chars	digits:String	Called when entering first 6 characters of a card number and returns them as a parameter.
cancelInstallment		Called when deleting all characters.

4.2 Getting the cards list (getMasterpassCards)

The method provides possibility to get a list of existing cards for the wallet by the phone number specified in AuthService#authorize.

getMasterpassCards method parameters

Parameter	Type	Description	Example
getCardsListener	GetCardsListener	Asynchronous callback with the result of receiving cards

GetCardsListener

void onSuccess(final List<MasterpassCard> cards)

void onError(final Throwable throwable)

GetCardsListener methods

Method	Parameters	Description
onSuccess	cards:List<MasterpassCard>	Called after the cards are received successfully. In case of success, the method returns a list of MasterpassCard objects.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

MasterpassCard object

Field	Type	Description	Nullability
maskedPan	String	Masked card number in 444433********11 format.	Nonnull
name	String	Unique card name in a Masterpass wallet.	Nonnull

Example:

CardService cardService = PortmoneSDK.getCardService();

cardService.getMasterpassCards(new GetCardsListener() {
  @Override
  public void onSuccess(final List<MasterpassCard> cards) {
     // success
  }

  @Override
  public void onError(final Throwable throwable) {
    // error occurred
  }
});

4.3 Deleting a card (deleteMasterpassCard)

This method deletes the card from the Masterpass wallet.

deleteMasterpassCard method parameters

Parameter	Type	Description	Example
cardName	String	Card name in the Masterpass system. It can be obtained from MasterpassCard#getName()	“Card name”
listener	DeleteCardListener	Asynchronous callback with the result of deleting a card

DeleteCardsListener

void onSuccess()

void onError(Throwable throwable)

DeleteCardsListener methods

Method	Parameters	Description
onSuccess		Called after a card is deleted successfully.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

Example:

CardService cardService = PortmoneSDK.getCardService();
MasterpassCard card;
cardService.deleteMasterpassCard(card.getName(), new DeleteCardListener() {

  @Override
  public void onSuccess() {
     //delete success
  }

  @Override
  public void onError(final Throwable throwable) {
     //error occurred
  }
});

5. OTP verification (validateCode)

The method provides possibility to perform OTP validation of the phone number and bank card. Called when error codes 2113 or 2114 are received. Can be called using AuthService#validateCode and CardService#validateCode. After a successful validation, it may be necessary to perform an additional verification. In that case, the result may be an error stating that it's necessary to perform the verification with repeated method call.

validateCode(MasterPassEditText code, ValidateCodeListener listener);

validateCode method parameters

Parameter	Type	Description
code	MasterPassEditText	MasterpassEditText object with a filled in code for validation. The following attributes should be specified: xmlns:masterpass="http://schemas.android.com/apk/res-auto" android:inputType="numberPassword" android:maxLength="6" masterpass:type="4"
listener	ValidateCodeListener	Asynchronous callback with validation result.

Example of the code parameter:

<cardtek.masterpass.attributes.MasterPassEditText
android:id="@+id/pin"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:hint="Enter Pin"
android:inputType="numberPassword"
android:maxLength="6"
masterpass:type="4"/>

ValidateCodeListener

void onSuccess()

void onError(Throwable throwable)

ValidateCodeListener methods

Method	Parameters	Description
onSuccess		Called after successful validation.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object. Possible errors 2113 and 2114, which require OTP validation.

6. Getting companies (PayeeService)

The service provides possibility to get a list of companies to which a payment can be made using the SDK. The object is obtained using PortmoneSDK.getPayeeService().

PayeeService

void getPayees(GetPayeeListener getPayeeListener);

getPayees method parameters

Parameters	Type	Description	Example
listener	GetPayeeListener	Asynchronous callback with the result of receiving companies.

GetPayeeListener

void onSuccess(List<Payee> payees);

void onError(Throwable throwable);

GetPayeeListener methods

Method	Parameters	Description
onSuccess	payees: List	Called after a list of companies is received successfully.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

Payee object

Field	Type	Description	Nullability
payeeId	String	Unique identifier of a company	Nonnull
name	String	Company name	Nonnull
contractNumberTitle	HashMap<String,String>	Name of the account number. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	Nonnull
contractNumberType	String	Data type for the account number. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	Nonnull
contractNumberSize	String	Maximum field size.	Nullable
attribute1Title	HashMap<String,String>	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	Nullable
attribute1Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	Nullable
attribute1Size	String	Maximum field size.	Nullable
attribute1ForInfo	boolean	If true, the field should not be shown	Nullable
attribute2Title	HashMap<String,String>	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	Nullable
attribute2Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	Nullable
attribute2Size	String	Maximum field size.	Nullable
attribute2ForInfo	boolean	If true, the field should not be shown	Nullable
attribute3Title	HashMap<String,String>	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	Nullable
attribute3Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	Nullable
attribute3Size	String	Maximum field size.	Nullable
attribute3ForInfo	boolean	If true, the field should not be shown	Nullable
attribute4Title	HashMap<String,String>	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	Nullable
attribute4Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	Nullable
attribute4Size	String	Maximum field size.	Nullable
attribute4ForInfo	boolean	If true, the field should not be shown	Nullable
imageUrl	String	Url of the image for this company	Nullable
needRedirect	boolean	Determines if a user should be redirected to the site to pay to this company	Nonnull
gateway	HashMap<String, String>	Url to pay to this company (the url to which a user will be redirected to make a payment on the site when the company cannot be displayed in the application). Contains options for 3 languages on the keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	Nullable

Example:

final PayeeService payeeService = PortmoneSDK.getPayeeService();

payeeService.getPayees(new GetPayeeListener() {
  @Override
  public void onSuccess(final List<Payee> list) {
     // request success
  }

  @Override
  public void onError(final Throwable throwable) {
     // error occurred
  }
});

7. Payment (PayeePaymentService)

The service provides possibility to pay by company.

PayeePaymentService

  void getCommission(
        final CommissionParams commissionParams,
        final String payeeId,
        final CommissionListener<PayeePaymentTransaction> listener
  );

  void proceedPayment(
        final PayeePaymentTransaction transaction,
        final PaymentParams paymentParams,
        final PayeePaymentListener listener
  );

  void start2dCardVerification(
        final PayeePaymentTransaction transaction,
        final String cvv,
        final Start2dListener<PayeePaymentTransaction> listener
  );

  void finish2dCardVerification(
        final PayeePaymentTransaction transaction,
        final String verificationCode,
        final Verify2dListener<PayeePaymentTransaction> listener
  );

PayeePaymentTransaction object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object for the card which you've received using CardService.getCards();	NonNull
billAmount	float	Amount of the payment	NonNull
payeeId	String	ID of the company in the Portmone system	NonNull
commission	float	Commission for the current payment	NonNull
bill	Bill	Object with payment information. Filled in after successful payment completion.	Nullable

Bill object

Field	Type	Description	Nullability
billId	String	Unique payment ID.	Nullable
recieptUrl	String	Link to get a pdf receipt.	Nullable
contractNumber	String	Personal account number.	Nullable
payDate	long	Time of payment in milliseconds.	Nullable

7.1 Getting a commission (getCommission)

The first step to make a payment is to get a commission for this payment. Successful result of getting the commission is the PayeePaymentTransaction object, which is required for further payment.

getCommission method parameters

Parameter	Type	Description
commissionParams	CommissionParams	A set of parameters required for getting the commission.
payeeId	String	ID of the company, to which payment is made, in the Portmone system.
listener	CommissionListener	Asynchronous callback with the result of getting the commission.

CommissionParams object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object for the card which you've received using CardService.getCards();	Nonnull
billAmount	float	Amount of the payment. Should be not less than 0.	Nonnull
merchantLogin	String	Login to pay to this company	Nonnull
billNumber	String	Unique generated account number	Nonnull

CommissionListener

void onCommissionSuccess(PayeePaymentTransaction paymentTransaction);

void onError(Throwable throwable);

CommissionListener methods

Method	Parameters	Description
onCommissionSuccess	paymentTransaction: PayeePaymentTransaction	Transaction object. Returned in case of successful getting the commission
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

7.2 Making a payment (proceedPayment)

proceedPayment method parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	The transaction object received from CommissionListener.onCommissionSuccess()
paymentParams	PaymentParams	Object with a set of parameters required for the payment.
listener	PayeePaymentListener	Asynchronous callback with the payment result.

PaymentParams object

Field	Type	Description	Nullability
contractNumber	String	Personal account number (*)	Nonnull
attribute1	String	Payment attribute 1. (*)	Nullable
attribute2	String	Payment attribute 2. (*)	Nullable
attribute3	String	Payment attribute 3. (*)	Nullable
attribute4	String	Payment attribute 4. (*)	Nullable
email	String	E-mail address to which a receipt will be sent.	Nullable

* The fields contractNumber, attribute 1-4 must correspond to the fields of the Payee object and must be filled in the appropriate order.

PayeePaymentListener

void onPaymentSuccess(PayeePaymentTransaction transaction);

void on2dVerificationNeeded(PayeePaymentTransaction transaction);

void on3dsVerificationNeeded(PayeePaymentTransaction transaction);

void onError(Throwable error);

PayeePaymentListener methods

Method	Parameters	Description
onPaymentSuccess	paymentTransaction: PayeePaymentTransaction	Called in case of successful payment. The transaction is filled with the Bill object.
on2dVerificationNeeded	paymentTransaction: PayeePaymentTransaction	Called when 2d verification of the card is needed.
on3dVerificationNeeded	paymentTransaction: PayeePaymentTransaction	Called when 3d verification of the card is needed.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

7.3 2d Verification of a card (start2dVerification, finish2dVerification)

2d Verification is carried out in 2 steps. At the first step, the start2dVerification method is called, where the card is checked and validated. After its successful completion an SMS with the verification code required for the second step is sent to the phone number associated with the card. At the second step, the finish2dVerification method is called. The payment is completed successfully after getting successful result after this step.

start2dVerification method parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	The transaction object received from PayeePaymentListener.on2dVerificaitonNeeded()
cvv	String	CVV code of the card for which verification is required.
listener	Start2dListener	Asynchronous callback with the result of verification start.

Start2dListener

void onStart2dSuccess(PayeePaymentTransaction transaction);

void onError(Throwable error);

Start2dListener methods

Method	Parameters	Description
onStart2dSuccess	paymentTransaction: PayeePaymentTransaction	Called in case the 2d verification was successfully started. The SMS with the verification code is sent to the mobile phone number.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

finish2dVerification method parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	The transaction object received from Start2dListener.onStart2dSuccess()
verificationCode	String	Verification code received in SMS.
listener	Verify2dListener	Asynchronous callback with the result of verification.

Verify2dListener

void onVerify2dSuccess(PayeePaymentTransaction transaction);

void onError(Throwable error);

Verify2dListener methods

Method	Parameters	Description
onVerify2dSuccess	paymentTransaction: PayeePaymentTransaction	Called in case the verification and the payment were successfully completed.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

7.4 3d Verification of a card (PortmoneWebView)

Calling the on3dVerificationNeeded method from the PayeePaymentListener means that 3d Verification is required for payment by this card. 3d Verification of the card is performed using PortmoneWebView.

The PortmoneWebView object, like any View element can be created in 2 ways:

• created as an element in *.xml file:

<com.portmone.sdk.util.PortmoneWebView
  android:id="@+id/portmone_web_view"
  android:layout_width="match_parent"
  android:layout_height="match_parent"/>

• created as an object and added to the container:

ViewGroup wrapper;

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_verify3d_bill);
  PayeePaymentTransaction transaction = (PayeePaymentTransaction)
getIntent().getSerializableExtra("transaction");
  wrapper = findViewById(R.id.wrapper);

  PortmoneWebView pmWebView = new PortmoneWebView(this);
  wrapper.addView(pmWebView);

  pmWebView.setVerify3dData(transaction, this);
}

To perform the verification you should create and initialize the PortmoneWebView object and call the setVerify3dData method.

setVerify3dData method parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	The transaction object received from PayeePaymentListener.on3dVerificationNeeded()
listener	Verify3dListener	Asynchronous callback with the result of verification.

Verify3dListener

void onVerify3dSuccess(PayeePaymentTransaction transaction);

 void onReceivedError(
        final WebView view,
        final WebResourceRequest req,
        final WebResourceError resourceError
 );

 void onError(Throwable error);

Verify3dListener methods

Method	Parameters	Description
onVerify3dSuccess	paymentTransaction: PayeePaymentTransaction	Called in case the verification and the payment were successfully completed.
onReceivedError	-	Standard callback with an error from the WebViewClient.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

8. Adding funds to a mobile phone account (TopUpMobileService)

The service provides possibility to top up mobile phone account.

TopUpMobileService

  void getCommission(
        final CommissionParams commissionParams,
        final String phoneNumber,
        final CommissionListener<TopUpMobileTranasaction> listener
  );

  void proceedPayment(
        final TopUpMobileTranasactiontransaction,
        final TopUpMobilePaymentListener listener
  );

  void start2dCardVerification(
        final TopUpMobileTranasaction transaction,
        final String cvv,
        final Start2dListener<TopUpMobileTranasaction> listener
  );

  void finish2dCardVerification(
        final TopUpMobileTranasaction transaction,
        final String verificationCode,
        final Verify2dListener<TopUpMobileTranasaction> listener
  );

TopUpMobileTransaction object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object for the card which you'he received using CardService.getCards();	Nonnull
billAmount	float	Amount of the payment.	Nonnull
phoneNumber	String	Phone number to which funds are transferred.	Nonnull
commission	float	Commission for the current payment.	Nonnull
payeeId	String	ID of the company in the Portmone system.	Nonnull
bill	Bill	Object with payment information. Filled in after the payment is successfully completed.	Nullable

Bill object

Field	Type	Description	Nullability
billId	String	Unique payment ID.	Nullable
recieptUrl	String	Link to get a pdf receipt.	Nullable
contractNumber	String	Personal account number.	Nullable
payDate	long	Time of payment in milliseconds.	Nullable

8.1 Getting a commission (getCommission)

The first step to make a payment is to get a commission for this payment. Successful result of getting the commission is the TopUpMobileTransaction object, which is required for further payment.

getCommission method parameters

Parameter	Type	Description
commissionParams	CommissionParams	A set of parameters required for getting the commission.
phoneNumber	String	Phone number to which funds are transferred.
listener	CommissionListener	Asynchronous callback with the result of getting the commission.

CommissionParams object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object for the card which you'he received using CardService.getCards();	Nonnull
billAmount	float	Amount of the payment. Should be not less than 0.	Nonnull
merchantLogin	String	Login to pay for this company.	Nonnull
billNumber	String	Unique generated account number.	Nonnull

CommissionListener

void onCommissionSuccess(TopUpTransaction paymentTransaction);

void onError(Throwable throwable);

CommissionListener methods

Method	Parameters	Description
onCommissionSuccess	paymentTransaction: TopUpMobileTransaction	Transaction object. Returned in case of successful getting the commission
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

8.2 Making a payment (proceedPayment)

proceedPayment method parameters

Parameter	Type	Description
transaction	TopUpMobileTransaction	The transaction object received from CommissionListener.onCommissionSuccess()
listener	TopUpMobilePaymentListener	Asynchronous callback with the payment result.

TopUpMobilePaymentListener

void onPaymentSuccess(TopUpMobileTransaction transaction);

void on2dVerificationNeeded(TopUpMobileTransaction transaction);

void on3dsVerificationNeeded(TopUpMobileTransaction transaction);

void onError(Throwable error);

TopUpMobilePaymentListener methods

Method	Parameters	Description
onPaymentSuccess	paymentTransaction: TopUpMobileTransaction	Called in case of successful payment. The transaction is filled with the Bill object.
on2dVerificationNeeded	paymentTransaction: TopUpMobileTransaction	Called when 2d verification of the card is needed.
on3dVerificationNeeded	paymentTransaction: TopUpMobileTransaction	Called when 3d verification of the card is needed.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

8.3 2d Verification of a card (start2dVerification, finish2dVerification)

2d Verification is carried out in 2 steps. At the first step, the start2dVerification method is called, where the card is checked and validated. After its successful completion an SMS with the verification code required for the second step is sent to the phone number associated with the card. At the second step, the finish2dVerification method is called. The payment is completed successfully after getting a successful result after this step.

start2dVerification method parameters

Parameter	Type	Description
transaction	TopUpMobileTransaction	The transaction object received from TopUpMobilePaymentListener.on2dVerificaitonNeeded()
cvv	String	CVV code of the card for which verification is required.
listener	Start2dListener	Asynchronous callback with the result of verification start.

Start2dListener

void onStart2dSuccess(TopUpMobileTransaction transaction);

void onError(Throwable error);

Start2dListener mehtods

Method	Parameters	Description
onStart2dSuccess	paymentTransaction: TopUpMobileTransaction	Called in case the 2d verification was successfully started. The SMS with the verification code is sent to the mobile phone number.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

finish2dVerification method parameters

Parameter	Type	Description
transaction	TopUpMobileTransaction	The transaction object received from Start2dListener.onStart2dSuccess()
verificationCode	String	Verification code received in SMS.
listener	Verify2dListener	Asynchronous callback with the result of verification.

Verify2dListener

void onVerify2dSuccess(TopUpMobileTansaction transaction);

void onError(Throwable error);

Verify2dListener methods

Method	Parameters	Description
onVerify2dSuccess	paymentTransaction: TopUpMobileTransaction	Called in case the verification and the payment were successfully completed.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

8.4 3d Verification of a card (PortmoneWebView)

Calling the on3dVerificationNeeded method from the PayeePaymentListener means that 3d Verification is required for payment by this card. 3d verification of the card is done using PortmoneWebView.

The PortmoneWebView object, like any View element can be created in 2 ways:

• created as an element in *.xml file:

<com.portmone.sdk.util.PortmoneWebView
  android:id="@+id/portmone_web_view"
  android:layout_width="match_parent"
  android:layout_height="match_parent"/>

• created as an object and added to the container:

ViewGroup wrapper;

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_verify3d_bill);
  PayeePaymentTransaction transaction = (PayeePaymentTransaction)
getIntent().getSerializableExtra("transaction");
  wrapper = findViewById(R.id.wrapper);

  PortmoneWebView pmWebView = new PortmoneWebView(this);
  wrapper.addView(pmWebView);

  pmWebView.setVerify3dData(transaction, this);
}

To perform the verification you should create and initialize the PortmoneWebView object and call the setVerify3dData method.

setVerify3dData method parameters

Parameter	Type	Description
transaction	TopUpMobileTransaction	The transaction object received from TopUpMobilePaymentListener.on3dVerificationNeeded()
listener	Verify3dListener	Asynchronous callback with the result of verification

Verify3dListener

 void onVerify3dSuccess(TopUpMobileTransaction transaction);

 void onReceivedError(
        final WebView view,
        final WebResourceRequest req,
        final WebResourceError resourceError
 );

 void onError(Throwable error);

Verify3dListener methods

Method	Parameters	Description
onVerify3dSuccess	paymentTransaction: TopUpMobileTransaction	Called in case the verification and the payment were successfully completed.
onReceivedError	-	Standard callback with an error from the WebViewClient.
onError	throwable:Throwable	Called when an error occurs during this operation. The parameter may be a system error or a PMError object.

9. List of possible errors

SDK internal errors

Code	Description
2000	Authorization error. Please call AuthorizationService#authorize() before.
2004	Bill amount cannot be less than 0.
2005	Phone number is invalid.
2006	Phone number cannot be empty.
2007	Transaction object is not valid. Please use transaction from proceedPayment() call.
2008	Transaction object is not valid. Please use transaction from getCommission() call.
2009	Verification code cannot be empty.
2010	PayeeId cannot be empty.
2011	Contract number cannot be empty.
2012	User id cannot be empty.
2013	No gate type found for this payee. Payment cannot be proceeded!
2014	Transaction object is not valid. Please use transaction from start2dVerification() call.
2015	CVV cannot be empty.
2016	Initialized params cannot be empty. Please call initialize method
2017	Merchant login cannot be empty.
2018	Card verification error.

Portmone server errors are also possible, in the same format.

Masterpass errors

Code	Description
2100	Internal Error
2101	Connection Error
2102	Card Number is empty
2103	Card Number is invalid
2104	CVV/CVC2 is empty
2105	CVV/CVC2 is invalid
2106	Card Name is empty
2107	Validation Code is empty
2108	Validation Code is invalid
2109	3D Url is empty
2110	3D Secure is not validated
2111	Terms & Condition checkbox is not selected
2112	Expire Year is invalid
2113	OTP sending card's Bank is required.
2114	MasterPass OTP is required for phone number validation.
2200	*Masterpass service server error.

Portmone and Masterpass service errors will be passed using the PMError object that is the child of the Throwable class.

PMError object

Field	Type	Description	Nullability
code	int	Error code	Nonnull
message	String	Error description	Nonnull