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:
- Go to https://developer.mastercard.com/account/sign-up
- Complete the registration form and then go through the e-mail confirmation procedure
- 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 |
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
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 |