Документація

Документація

  • EN
  • UK

›Documentation

Документація

  • Payment Gateway
  • PortmoneDirect
  • Google Pay
  • Apple Pay
  • Structured Link
  • iOS E-com SDK
  • Android E-com SDK
  • Masterpass iOS SDK
  • Masterpass Android SDK
  • H2H JSON ASYNC для PCI DSS
  • Visa/Masterpass Products

Documentation

  • Payment Gateway
  • PortmoneDirect
  • Google Pay
  • Apple Pay
  • Structured Link
  • iOS E-com SDK
  • Android E-com SDK
  • Masterpass iOS SDK
  • Masterpass Android SDK
  • H2H JSON ASYNC for PCI DSS
  • Visa/Masterpass Products

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

FieldTypeDescriptionNullability
clientIdStringA unique identifier of the client in the Masterpass systemNonnull
merchantKeyStringUnique keyNonnull

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.

Authorization

AuthService

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

authorize method parameters

ParameterTypeDescriptionExample
phoneNumberStringUser mobile phone number. Used as an identifier in the Masterpass wallet.“380666789555”
userIdStringUser ID in the Portmone system. Required for identification in the Portmone system.“3715100”
loginListenerLoginListenerAsynchronous callback with the result of authorization.

Getting authorization result:

LoginListener

void onSuccess();

void onError(Throwable throwable);

LoginListener methods

MethodParametersDescription
onSuccessCalled after successful authorization in the system.
onErrorthrowable:ThrowableCalled 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.

Adding a card

addMasterpassCard method parameters

ParameterTypeDescriptionExample
cardNumberMasterPassEditTextThe 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
expireMonthintCard expiration month12
expireYearintCard expiration year2020 or 20
cardNameStringA unique card name in the wallet“Card Name”
cvvMasterpassEditTextThe 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
termsConditionsCheckBoxConfirmation of the Masterpass rules acceptance
addCardListenerAddCardListenerAsynchronous 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

MethodParametersDescription
onSuccessCalled after a card is added successfully.
onErrorthrowable:ThrowableCalled 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

MethodParametersDescription
getFirstCharfirstChar:charCalled when entering first character of a card number and returns it as a parameter.
getFirst6Charsdigits:StringCalled when entering first 6 characters of a card number and returns them as a parameter.
cancelInstallmentCalled 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.

Getting the cards list

getMasterpassCards method parameters

ParameterTypeDescriptionExample
getCardsListenerGetCardsListenerAsynchronous callback with the result of receiving cards

GetCardsListener

void onSuccess(final List<MasterpassCard> cards)

void onError(final Throwable throwable)

GetCardsListener methods

MethodParametersDescription
onSuccesscards:List<MasterpassCard>Called after the cards are received successfully. In case of success, the method returns a list of MasterpassCard objects.
onErrorthrowable:ThrowableCalled when an error occurs during this operation. The parameter may be a system error or a PMError object.

MasterpassCard object

FieldTypeDescriptionNullability
maskedPanStringMasked card number in 444433********11 format.Nonnull
nameStringUnique 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.

Deleting a card

deleteMasterpassCard method parameters

ParameterTypeDescriptionExample
cardNameStringCard name in the Masterpass system. It can be obtained from MasterpassCard#getName()“Card name”
listenerDeleteCardListenerAsynchronous callback with the result of deleting a card

DeleteCardsListener

void onSuccess()

void onError(Throwable throwable)

DeleteCardsListener methods

MethodParametersDescription
onSuccessCalled after a card is deleted successfully.
onErrorthrowable:ThrowableCalled 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

ParameterTypeDescription
codeMasterPassEditTextMasterpassEditText 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"
listenerValidateCodeListenerAsynchronous 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

MethodParametersDescription
onSuccessCalled after successful validation.
onErrorthrowable:ThrowableCalled 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

ParametersTypeDescriptionExample
listenerGetPayeeListenerAsynchronous callback with the result of receiving companies.

GetPayeeListener

void onSuccess(List<Payee> payees);

void onError(Throwable throwable);

GetPayeeListener methods

MethodParametersDescription
onSuccesspayees: ListCalled after a list of companies is received successfully.
onErrorthrowable:ThrowableCalled when an error occurs during this operation. The parameter may be a system error or a PMError object.

Payee object

FieldTypeDescriptionNullability
payeeIdStringUnique identifier of a companyNonnull
nameStringCompany nameNonnull
contractNumberTitleHashMap<String,String>Name of the account number. Contains translations into 3 languages by keys:
“uk ” = Ukrainian,
“en” = English,
“ru” = Russian.
Nonnull
contractNumberTypeStringData type for the account number. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
Nonnull
contractNumberSizeStringMaximum field size.Nullable
attribute1TitleHashMap<String,String>Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.Nullable
attribute1TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
Nullable
attribute1SizeStringMaximum field size.Nullable
attribute1ForInfobooleanIf true, the field should not be shownNullable
attribute2TitleHashMap<String,String>Attribute name. Contains translations into 3 languages by keys:
“uk ” = Ukrainian,
“en” = English,
“ru” = Russian.
Nullable
attribute2TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
Nullable
attribute2SizeStringMaximum field size.Nullable
attribute2ForInfobooleanIf true, the field should not be shownNullable
attribute3TitleHashMap<String,String>Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.Nullable
attribute3TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
Nullable
attribute3SizeStringMaximum field size.Nullable
attribute3ForInfobooleanIf true, the field should not be shownNullable
attribute4TitleHashMap<String,String>Attribute name. Contains translations into 3 languages by keys:
“uk ” = Ukrainian,
“en” = English,
“ru” = Russian.
Nullable
attribute4TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
Nullable
attribute4SizeStringMaximum field size.Nullable
attribute4ForInfobooleanIf true, the field should not be shownNullable
imageUrlStringUrl of the image for this companyNullable
needRedirectbooleanDetermines if a user should be redirected to the site to pay to this companyNonnull
gatewayHashMap<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.

Payment

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

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object for the card which you've received using CardService.getCards();NonNull
billAmountfloatAmount of the paymentNonNull
payeeIdStringID of the company in the Portmone systemNonNull
commissionfloatCommission for the current paymentNonNull
billBillObject with payment information. Filled in after successful payment completion.Nullable

Bill object

FieldTypeDescriptionNullability
billIdStringUnique payment ID.Nullable
recieptUrlStringLink to get a pdf receipt.Nullable
contractNumberStringPersonal account number.Nullable
payDatelongTime 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

ParameterTypeDescription
commissionParamsCommissionParamsA set of parameters required for getting the commission.
payeeIdStringID of the company, to which payment is made, in the Portmone system.
listenerCommissionListenerAsynchronous callback with the result of getting the commission.

CommissionParams object

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object for the card which you've received using CardService.getCards();Nonnull
billAmountfloatAmount of the payment. Should be not less than 0.Nonnull
merchantLoginStringLogin to pay to this companyNonnull
billNumberStringUnique generated account numberNonnull

CommissionListener

void onCommissionSuccess(PayeePaymentTransaction paymentTransaction);

void onError(Throwable throwable);

CommissionListener methods

MethodParametersDescription
onCommissionSuccesspaymentTransaction: PayeePaymentTransactionTransaction object. Returned in case of successful getting the commission
onErrorthrowable:ThrowableCalled 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

ParameterTypeDescription
transactionPayeePaymentTransactionThe transaction object received from CommissionListener.onCommissionSuccess()
paymentParamsPaymentParamsObject with a set of parameters required for the payment.
listenerPayeePaymentListenerAsynchronous callback with the payment result.

PaymentParams object

FieldTypeDescriptionNullability
contractNumberStringPersonal account number (*)Nonnull
attribute1StringPayment attribute 1. (*)Nullable
attribute2StringPayment attribute 2. (*)Nullable
attribute3StringPayment attribute 3. (*)Nullable
attribute4StringPayment attribute 4. (*)Nullable
emailStringE-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

MethodParametersDescription
onPaymentSuccesspaymentTransaction: PayeePaymentTransactionCalled in case of successful payment. The transaction is filled with the Bill object.
on2dVerificationNeededpaymentTransaction: PayeePaymentTransactionCalled when 2d verification of the card is needed.
on3dVerificationNeededpaymentTransaction: PayeePaymentTransactionCalled when 3d verification of the card is needed.
onErrorthrowable:ThrowableCalled 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.

2d verification of the card

start2dVerification method parameters

ParameterTypeDescription
transactionPayeePaymentTransactionThe transaction object received from PayeePaymentListener.on2dVerificaitonNeeded()
cvvStringCVV code of the card for which verification is required.
listenerStart2dListenerAsynchronous callback with the result of verification start.

Start2dListener

void onStart2dSuccess(PayeePaymentTransaction transaction);

void onError(Throwable error);

Start2dListener methods

MethodParametersDescription
onStart2dSuccesspaymentTransaction: PayeePaymentTransactionCalled in case the 2d verification was successfully started. The SMS with the verification code is sent to the mobile phone number.
onErrorthrowable:ThrowableCalled when an error occurs during this operation. The parameter may be a system error or a PMError object.

finish2dVerification method parameters

ParameterTypeDescription
transactionPayeePaymentTransactionThe transaction object received from Start2dListener.onStart2dSuccess()
verificationCodeStringVerification code received in SMS.
listenerVerify2dListenerAsynchronous callback with the result of verification.

Verify2dListener

void onVerify2dSuccess(PayeePaymentTransaction transaction);

void onError(Throwable error);

Verify2dListener methods

MethodParametersDescription
onVerify2dSuccesspaymentTransaction: PayeePaymentTransactionCalled in case the verification and the payment were successfully completed.
onErrorthrowable:ThrowableCalled 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.

3d Verification of the card

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

ParameterTypeDescription
transactionPayeePaymentTransactionThe transaction object received from PayeePaymentListener.on3dVerificationNeeded()
listenerVerify3dListenerAsynchronous 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

MethodParametersDescription
onVerify3dSuccesspaymentTransaction: PayeePaymentTransactionCalled in case the verification and the payment were successfully completed.
onReceivedError-Standard callback with an error from the WebViewClient.
onErrorthrowable:ThrowableCalled 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.

Replenishment of mobile phone

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

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object for the card which you'he received using CardService.getCards();Nonnull
billAmountfloatAmount of the payment.Nonnull
phoneNumberStringPhone number to which funds are transferred.Nonnull
commissionfloatCommission for the current payment.Nonnull
payeeIdStringID of the company in the Portmone system.Nonnull
billBillObject with payment information. Filled in after the payment is successfully completed.Nullable

Bill object

FieldTypeDescriptionNullability
billIdStringUnique payment ID.Nullable
recieptUrlStringLink to get a pdf receipt.Nullable
contractNumberStringPersonal account number.Nullable
payDatelongTime 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

ParameterTypeDescription
commissionParamsCommissionParamsA set of parameters required for getting the commission.
phoneNumberStringPhone number to which funds are transferred.
listenerCommissionListenerAsynchronous callback with the result of getting the commission.

CommissionParams object

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object for the card which you'he received using CardService.getCards();Nonnull
billAmountfloatAmount of the payment. Should be not less than 0.Nonnull
merchantLoginStringLogin to pay for this company.Nonnull
billNumberStringUnique generated account number.Nonnull

CommissionListener

void onCommissionSuccess(TopUpTransaction paymentTransaction);

void onError(Throwable throwable);

CommissionListener methods

MethodParametersDescription
onCommissionSuccesspaymentTransaction: TopUpMobileTransactionTransaction object. Returned in case of successful getting the commission
onErrorthrowable:ThrowableCalled 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

ParameterTypeDescription
transactionTopUpMobileTransactionThe transaction object received from CommissionListener.onCommissionSuccess()
listenerTopUpMobilePaymentListenerAsynchronous callback with the payment result.

TopUpMobilePaymentListener

void onPaymentSuccess(TopUpMobileTransaction transaction);

void on2dVerificationNeeded(TopUpMobileTransaction transaction);

void on3dsVerificationNeeded(TopUpMobileTransaction transaction);

void onError(Throwable error);

TopUpMobilePaymentListener methods

MethodParametersDescription
onPaymentSuccesspaymentTransaction: TopUpMobileTransactionCalled in case of successful payment. The transaction is filled with the Bill object.
on2dVerificationNeededpaymentTransaction: TopUpMobileTransactionCalled when 2d verification of the card is needed.
on3dVerificationNeededpaymentTransaction: TopUpMobileTransactionCalled when 3d verification of the card is needed.
onErrorthrowable:ThrowableCalled 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.

2d verification of the card

start2dVerification method parameters

ParameterTypeDescription
transactionTopUpMobileTransactionThe transaction object received from TopUpMobilePaymentListener.on2dVerificaitonNeeded()
cvvStringCVV code of the card for which verification is required.
listenerStart2dListenerAsynchronous callback with the result of verification start.

Start2dListener

void onStart2dSuccess(TopUpMobileTransaction transaction);

void onError(Throwable error);

Start2dListener mehtods

MethodParametersDescription
onStart2dSuccesspaymentTransaction: TopUpMobileTransactionCalled in case the 2d verification was successfully started. The SMS with the verification code is sent to the mobile phone number.
onErrorthrowable:ThrowableCalled when an error occurs during this operation. The parameter may be a system error or a PMError object.

finish2dVerification method parameters

ParameterTypeDescription
transactionTopUpMobileTransactionThe transaction object received from Start2dListener.onStart2dSuccess()
verificationCodeStringVerification code received in SMS.
listenerVerify2dListenerAsynchronous callback with the result of verification.

Verify2dListener

void onVerify2dSuccess(TopUpMobileTansaction transaction);

void onError(Throwable error);

Verify2dListener methods

MethodParametersDescription
onVerify2dSuccesspaymentTransaction: TopUpMobileTransactionCalled in case the verification and the payment were successfully completed.
onErrorthrowable:ThrowableCalled 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.

3d Verification of the card

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

ParameterTypeDescription
transactionTopUpMobileTransactionThe transaction object received from TopUpMobilePaymentListener.on3dVerificationNeeded()
listenerVerify3dListenerAsynchronous 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

MethodParametersDescription
onVerify3dSuccesspaymentTransaction: TopUpMobileTransactionCalled in case the verification and the payment were successfully completed.
onReceivedError-Standard callback with an error from the WebViewClient.
onErrorthrowable:ThrowableCalled 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

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

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

Masterpass errors

CodeDescription
2100Internal Error
2101Connection Error
2102Card Number is empty
2103Card Number is invalid
2104CVV/CVC2 is empty
2105CVV/CVC2 is invalid
2106Card Name is empty
2107Validation Code is empty
2108Validation Code is invalid
21093D Url is empty
21103D Secure is not validated
2111Terms & Condition checkbox is not selected
2112Expire 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

FieldTypeDescriptionNullability
codeintError codeNonnull
messageStringError descriptionNonnull
← Masterpass iOS SDKH2H JSON ASYNC for PCI DSS →
  • Android integration
  • Opportunities provided by Portmone SDK
  • Before getting started
    • Sign up at Masterpass™
    • Sign up at Portmone.com
  • 1. AAR integration
  • 2. Get started with the SDK
  • 3. Authorization (AuthService)
  • 4. Masterpass wallet (CardService)
    • 4.1 Adding a card (addMasterpassCard)
    • 4.2 Getting the cards list (getMasterpassCards)
    • 4.3 Deleting a card (deleteMasterpassCard)
  • 5. OTP verification (validateCode)
  • 6. Getting companies (PayeeService)
  • 7. Payment (PayeePaymentService)
    • 7.1 Getting a commission (getCommission)
    • 7.2 Making a payment (proceedPayment)
    • 7.3 2d Verification of a card (start2dVerification, finish2dVerification)
    • 7.4 3d Verification of a card (PortmoneWebView)
  • 8. Adding funds to a mobile phone account (TopUpMobileService)
    • 8.1 Getting a commission (getCommission)
    • 8.2 Making a payment (proceedPayment)
    • 8.3 2d Verification of a card (start2dVerification, finish2dVerification)
    • 8.4 3d Verification of a card (PortmoneWebView)
  • 9. List of possible errors
Copyright © 2022 Portmone.com