Masterpass Android SDK
Android інтеграція
Portmone SDK підтримує версію Android 4.4 KitKat, API level 19 та пізніші версії.
Можливості, які надає Portmone SDK
Гаманець Masterpass:
- додавання картки до існуючого гаманця або створення нового;
- видалення карток з існуючого гаманця;
- отримання списку карток для існуючого гаманця.
Оплата:
- поповнення мобільного за допомогою карток Masterpass;
- оплата послуг за особовим рахунком за допомогою карток Masterpass.
Перед початком роботи
Реєстрація у Masterpass™
Для початку роботи з Masterpass™ необхідно пройти процес merchant-реєстрації на developers.mastercard.com. Для цього:
- Перейдіть на https://developer.mastercard.com/account/sign-up
- Заповніть анкетні дані та пройдіть процедуру підтвердження e-mail адреси
- Створіть проект на сторінці https://developer.mastercard.com/dashboard → Create new project
Реєстрація у Portmone.com
Після отримання ключів від Masterpass™, передайте Portmone.com наступну інформацію:
- Дані ключів з вашого особистого кабінету на https://developer.mastercard.com/masterpass/merchant/#/keyManagement2, а саме:
- Public key (Натисніть “Actions” → “Download *.pem”)
- Keystore password
- Key alias
- Masterpass™ Checkout ID (скопіювати зі сторінки https://developer.mastercard.com/masterpass/merchant/#/checkoutCredentials у вашому особистому кабінеті)
Передати інформацію необхідно листом на [email protected] з темою “Partner [Назва вашої компанії] Onboarding”. Будь ласка, перевірте що в вас є постійний доступ до поштової скриньки, з якої ви надсилатимете цей лист, та скринька зареєстрована у довіреному домені вашої компанії. Листи з публічних безкоштовних доменів (gmail.com, yahoo.com, ukr.net тощо) буде автоматично відфільтровано. Після реєстрації даних вашого Masterpass™ Merchant у системі Portmone.com, з вами зв’яжуться для допомоги у подальших кроках інтеграції та тестування і передадуть наступну інформацію:
- Portmone.com Merchant Id
- Portmone.com Merchant Login
- Поточну версію SDK для Android разом із зразком додатку, що використовує SDK.
1. Інтеграція aar
Додати файл portmone-v1.0.aar в папку libs.
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. Початок роботи з SDK
Для використання методів SDK перед початком роботи необхідно викликати метод, який приймає набір параметрів необхідних для роботи з сдк:
PortmoneSDK.init(Context, InitParams);
Об’єкт InitParams
Поле | Тип | Опис | Nullability |
---|---|---|---|
clientId | String | Унікальне ід клієнта в системі мастерпас | Nonnull |
merchantKey | String | Унікальний ключ | Nonnull |
3. Авторизація (AuthService)
Для використання можливостей SDK потрібно авторизуватися в системі. Для авторизації використовується AuthService, який отримується за допомогою PortmoneSDK.getAuthService() та його метод authorize. Авторизація для одного користувача зберігається протягом життя додатку після виклику методу. Для зміни користувача потрібно викликати цей метод знову з іншими параметрами.
Під час виклику методу відбувається перевірка статусу гаманця за вказаним номером телефону, в разі необхідності автоматично відбувається лінкування клієнта до системи Masterpass. В такому випадку необхідна верифікація карти за допомогою OTP коду і з’явиться помилка 2113.
AuthService
void authorize(
String phoneNumber,
String userId,
LoginListener loginListener
);
Параметри методу authorize
Параметр | Тип | Опис | Приклад |
---|---|---|---|
phoneNumber | String | Номер телефону користувача. Використовується як ідентифікатор в гаманці Masterpass. | “380666789555” |
userId | String | Ід користувача в Portmone. Потрібен для ідентифікації в системі Portmone. | “3715100” |
loginListener | LoginListener | Асинхронний колбек з результатом авторизації. |
Отримання результату авторизації:
LoginListener
void onSuccess();
void onError(Throwable throwable);
Методи LoginListener
Метод | Параметри | Опис |
---|---|---|
onSuccess | Викликається після успішній авторизації в системі | |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операціїПараметром може бути системна помилка або об’єкт PMError. При перевірці статусу гаманця можливе виникнення помилки 2113, при якій необхідна OTP верифікація карти. |
Приклад:
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 (CardService)
Для роботи з гаманцем використовується CardService. Об’єкт можна отримати за допомогою PortmoneSDK.getCardService(). Сервіс дає можливість додавати та видаляти картки, а також отримувати список карток в існуючому гаманці.
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 Додавання картки (addMasterpassCard)
Метод додає картку в існуючий гаманець Masterpass по номеру телефону вказаному при AuthService#authorize або створює новий гаманець, якщо за даним номером існуючого не було знайдено.
Параметри методу addMasterpassCard
Параметр | Тип | Опис | Приклад |
---|---|---|---|
cardNumber | MasterPassEditText | Номер картки заповнений у об’єкті MasterpassEditText. Наступні параметри повинні бути вказані xmlns:masterpass= "http://schemas.android.com/apk/res-auto" аndroid:inputType="number" android:digits="01234 56789" android:maxLength="19" masterpass:type="1" Методи getText() та setText() заборонені. Їх виклик призводить до помилки. | Див. нижче |
expireMonth | int | Місяць терміну дії картки | 12 |
expireYear | int | Рік терміну дії картки | 2020 або 20 |
cardName | String | Унікальне ім’я карти в гаманці | “Card Name” |
cvv | MasterpassEditText | CVV код картки заповнений у об’єкті MasterpassEditText. Наступні параметри повинні бути вказані xmlns:masterpass= "http://schemas.android.com/apk/res-auto" аndroid:inputType="number" android:maxLength="4" masterpass:type="3" Методи getText() та setText() заборонені. Їх виклик призводить до помилки. | Див. нижче |
termsConditions | CheckBox | Підтвердження погодження з правилами Masterpass | |
addCardListener | AddCardListener | Асинхронний колбек з додавання карти. |
Приклад параметру cardNumber:
<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"/>
Приклад параметру cvv:
<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"/>
Отримання результату додавання карти:
AddCardListener
void onSuccess();
void onError(Throwable throwable);
Методи AddCardListener
Метод | Параметри | Опис |
---|---|---|
onSuccess | Викликається після успішного додавання картки. | |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.При додаванні картки можливе виникнення помилок 2113, 2114, при яких необхідна OTP верифікація картки та номеру телефону. |
Приклад:
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
}
}
);
}
Для MasterpassEditText з номером картки є можливітсь вказати CardTypeCallback - дає можливість отримати дані про введений номер карти для її ідентифікації. Вказується за допомогою методу MasterpasEditText#setCardTypeCallback.
CardTypeCallback
void getFirstChar(char firstChar)
void getFirst6Chars(String digits)
void cancelInstallment()
Методи CardTypeCallback
Метод | Параметри | Опис |
---|---|---|
getFirstChar | firstChar:char | Викликається при введенні першого символу номеру картки і його ж повертає як параметр. |
getFirst6Chars | digits:String | Викликається при введенні перших 6 символів номеру картки і їх ж повертає як параметр. |
cancelInstallment | Викликається при видаленні усіх символів. |
4.2 Отримання списку карток (getMasterpassCards)
Метод дозволяє отримати список існуючих карток для гаманця за номером телефону вказаному при AuthService#authorize.
Параметри методу getMasterpassCards
Параметр | Тип | Опис | Приклад |
---|---|---|---|
getCardsListener | GetCardsListener | Асинхронний колбек з результатом отримання карток |
GetCardsListener
void onSuccess(final List<MasterpassCard> cards)
void onError(final Throwable throwable)
Методи GetCardsListener
Метод | Параметри | Опис |
---|---|---|
onSuccess | cards:List<MasterpassCard> | Викликається після успішного отримання карток. При успішному запиті метод повертає список об’єктів MasterpassCard. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
Об‘єкт MasterpassCard
Поле | Тип | Опис | Nullability |
---|---|---|---|
maskedPan | String | Замаскований номер картки у форматі 444433********11. | Nonnull |
name | String | Унікальна назва картки в гаманці Masterpass. | Nonnull |
Приклад:
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 Видалення картки (deleteMasterpassCard)
Метод видаляє картку з гаманця Masterpass.
Параметри методу deleteMasterpassCard
Параметр | Тип | Опис | Приклад |
---|---|---|---|
cardName | String | Назва картки в системі Masterpass. Отримується з MasterpassCard#getName() | “Card name” |
listener | DeleteCardListener | Асинхронний колбек з результатом видалення |
DeleteCardsListener
void onSuccess()
void onError(Throwable throwable)
Методи DeleteCardsListener
Метод | Параметри | Опис |
---|---|---|
onSuccess | Викликається після успішного видалення картки. | |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
Приклад:
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 верифікація (validateCode)
Метод дозволяє проводити OTP валідацію номера телефону та банківської карти. Викликається при отриманні помилок з кодом 2113 або 2114. Може бути викликаний за допомогою AuthService#validateCode та CardService#validateCode. Після успішної перевірки може виникнути потреба в додатковій верифікації, тому результатом може бути помилка про необхідність верифікації з повторним викликом методу.
validateCode(MasterPassEditText code, ValidateCodeListener listener);
Параметри методу validateCode
Параметр | Тип | Опис |
---|---|---|
code | MasterPassEditText | Об’єкт MasterpassEditText з заповненим кодом для валідації. Наступні атрибути повинні бути вказані: xmlns:masterpass="http://schemas.android.com/apk/res-auto" android:inputType="numberPassword" android:maxLength="6" masterpass:type="4" |
listener | ValidateCodeListener | Асинхронний колбек з результатом перевірки. |
Приклад параметру code:
<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
Метод | Параметри | Опис |
---|---|---|
onSuccess | Викликається після успішної валідації. | |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. Можливі помилки 2113 і 2114, при який необхідна OTP валідація. |
6. Отримання компаній (PayeeService)
Сервіс дозволяє отримати компанії на які можна здійснювати оплату за допомогою SDK. Об’єкт отримується за допомогою PortmoneSDK.getPayeeService().
PayeeService
void getPayees(GetPayeeListener getPayeeListener);
Параметри методу getPayees
Параметр | Тип | Опис | Приклад |
---|---|---|---|
listener | GetPayeeListener | Асинхронний колбек з результатом отримання компаній. |
GetPayeeListener
void onSuccess(List<Payee> payees);
void onError(Throwable throwable);
Методи GetPayeeListener
Метод | Параметри | Опис |
---|---|---|
onSuccess | payees: List | Викликається після успішного отримання списку компаній. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
Об’єкт Payee
Поле | Тип | Опис | Nullability |
---|---|---|---|
payeeId | String | Унікальне ід компанії | Nonnull |
name | String | Назва компанії. | Nonnull |
contractNumberTitle | HashMap<String,String> | Назва номеру рахунку. Містить переклади на 3 мовах за ключами: “uk ” - українська, “en” = англійська, “ru” = російська | Nonnull |
contractNumberType | String | Тип даних для номеру рахунку. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy". | Nonnull |
contractNumberSize | String | Максимальний розмір поля. | Nullable |
attribute1Title | HashMap<String,String> | Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” - українська , “en” = англійська, “ru” = російська | Nullable |
attribute1Type | String | Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy". | Nullable |
attribute1Size | String | Максимальний розмір поля. | Nullable |
attribute1ForInfo | boolean | При значенні true означає що поле не має бути показане | Nullable |
attribute2Title | HashMap<String,String> | Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” - українська, “en” = англійська, “ru” = російська | Nullable |
attribute2Type | String | Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy". | Nullable |
attribute2Size | String | Максимальний розмір поля. | Nullable |
attribute2ForInfo | boolean | При значенні true означає що поле не має бути показане | Nullable |
attribute3Title | HashMap<String,String> | Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” - українська , “en” = англійська, “ru” = російська | Nullable |
attribute3Type | String | Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy". | Nullable |
attribute3Size | String | Максимальний розмір поля. | Nullable |
attribute3ForInfo | boolean | При значенні true означає що поле не має бути показане | Nullable |
attribute4Title | HashMap<String,String> | Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” - українська, “en” = англійська, “ru” = російська | Nullable |
attribute4Type | String | Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy". | Nullable |
attribute4Size | String | Максимальний розмір поля. | Nullable |
attribute4ForInfo | boolean | При значенні true означає що поле не має бути показане | Nullable |
imageUrl | String | Url з зображенням для даної компанії | Nullable |
needRedirect | boolean | Визначає чи потрібен перехід на сайт для оплати даної компанії | Nonnull |
gateway | HashMap<String, String> | Url для оплати даної компанії. Містить варіанти для 3 мов за ключами: “uk ” - українська, “en” = англійська, “ru” = російська | Nullable |
Приклад:
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. Оплата (PayeePaymentService)
Сервіс дозволяє здійснювати оплати по компаніях.
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
Поле | Тип | Опис | Nullability |
---|---|---|---|
card | MasterpassCard | Об’єкт карти мастерпасу отриманої за допомогою CardService.getCards(); | NonNull |
billAmount | float | Сума до оплати. | NonNull |
payeeId | String | Ід компанії в системі Portmone. | NonNull |
commission | float | Комісія для поточного платежу | NonNull |
bill | Bill | Об’єкт з інформацією про здійснену оплату, заповнюється після успішного завершення оплати. | Nullable |
Об’єкт Bill
Поле | Тип | Опис | Nullability |
---|---|---|---|
billId | String | Унікальне ід здійсненої оплати. | Nullable |
recieptUrl | String | Посилання на pdf з квитанцією. | Nullable |
contractNumber | String | Номер особового рахунку. | Nullable |
payDate | long | Час здійсненої оплати в мілісекундах. | Nullable |
7.1 Отримання комісії (getCommission)
Для здійснення оплати першим кроком є отримання комісії для даного платежу. Об’єкт PayeePaymentTransaction отриманий в результаті успішного отримання комісії необхідний для подальшого здійснення оплати.
Параметри методу getCommission
Параметр | Тип | Опис |
---|---|---|
commissionParams | CommissionParams | Набір параметрів необхідних для отримання комісії. |
payeeId | String | Іденитфікатор компанії на яку здійснюєтся оплата в системі Портмоне. |
listener | CommissionListener | Асинхронний колбек з результатом отримання комісії. |
Об’єкт CommissionParams
Поле | Тип | Опис | Nullability |
---|---|---|---|
card | MasterpassCard | Об’єкт карти мастерпасу отрманої за допомогою CardService.getCards(); | Nonnull |
billAmount | float | Сума до оплати, не повинна бути меншою 0. | Nonnull |
merchantLogin | String | Логін для оплати даної компанії | Nonnull |
billNumber | String | Унікальний згенерований номер рахунку. | Nonnull |
CommissionListener
void onCommissionSuccess(PayeePaymentTransaction paymentTransaction);
void onError(Throwable throwable);
Методи CommissionListener
Метод | Параметри | Опис |
---|---|---|
onCommissionSuccess | paymentTransaction: PayeePaymentTransaction | Об’єкт транзакції. Повертається в разі успішного отримання комісії |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
7.2 Проведення оплати (proceedPayment)
Параметри методу proceedPayment
Параметр | Тип | Опис |
---|---|---|
transaction | PayeePaymentTransaction | Об’єкт транзакції, отриманий з CommissionListener.onCommissionSuccess() |
paymentParams | PaymentParams | Об’єкт з набором параметрів необхідних для оплати. |
listener | PayeePaymentListener | Асинхронний колбек з результатом проведення оплати. |
Об’єкт PaymentParams
Поле | Тип | Опис | Nullability |
---|---|---|---|
contractNumber | String | Номер особового рахунку (*) | Nonnull |
attribute1 | String | Атрибут оплати 1. (*) | Nullable |
attribute2 | String | Атрибут оплати 2. (*) | Nullable |
attribute3 | String | Атрибут оплати 3. (*) | Nullable |
attribute4 | String | Атрибут оплати 4. (*) | Nullable |
String | Електронна пошта, на яку буде вислана квитанція. | Nullable |
* Поля contractNumber, attribute 1-4 повинні відповідати полям об’єкта Payee і заповнені у відповідному порядку.
PayeePaymentListener
void onPaymentSuccess(PayeePaymentTransaction transaction);
void on2dVerificationNeeded(PayeePaymentTransaction transaction);
void on3dsVerificationNeeded(PayeePaymentTransaction transaction);
void onError(Throwable error);
Методи PayeePaymentListener
Метод | Параметри | Опис |
---|---|---|
onPaymentSuccess | paymentTransaction: PayeePaymentTransaction | Викликається в разі успішного проведення оплати. Транзакція заповнена об’єктом Bill. |
on2dVerificationNeeded | paymentTransaction: PayeePaymentTransaction | Викликається в разі необхідності 2д верифікації карти. |
on3dVerificationNeeded | paymentTransaction: PayeePaymentTransaction | Викликається в разі необхідності 3д верифікації карти. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
7.3 Верифікація 2д карти (start2dVerification, finish2dVerification)
Проведення 2д верифікації відбувається в 2 етапи. Перший відбувається при виклику start2dVerification, де відбувається перевірка та валідація карти, після його успішного завершення на номер телефону прив’язаного до карти прийде смс з кодом верифікації, який необхідний для finish2dVerification. При успішному результаті останнього оплата успішно завершується.
Параметри методу start2dVerification
Параметр | Тип | Опис |
---|---|---|
transaction | PayeePaymentTransaction | Об’єкт транзакції, отриманий з PayeePaymentListener..on2dVerificaitonNeeded() |
cvv | String | Cvv код карти, якій необхідна верифікація. |
listener | Start2dListener | Асинхронний колбек з результатом початку верифікації. |
Start2dListener
void onStart2dSuccess(PayeePaymentTransaction transaction);
void onError(Throwable error);
Методи Start2dListener
Метод | Параметри | Опис |
---|---|---|
onStart2dSuccess | paymentTransaction: PayeePaymentTransaction | Викликаєтся в разі успішного початку 2д верифікації. На номер телефону відсилається смс з кодом для верифікації. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
Параметри методу finish2dVerification
Параметр | Тип | Опис |
---|---|---|
transaction | PayeePaymentTransaction | Об’єкт транзакції, отриманий з Start2dListener.onStart2dSuccess() |
verificationCode | String | Код верифікації отриманий в смс. |
listener | Verify2dListener | Асинхронний колбек з результатом верифікації. |
Verify2dListener
void onVerify2dSuccess(PayeePaymentTransaction transaction);
void onError(Throwable error);
Методи Verify2dListener
Метод | Параметри | Опис |
---|---|---|
onVerify2dSuccess | paymentTransaction: PayeePaymentTransaction | Викликаєтся в разі успішного завершення верифікації та успішного проведення оплати |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
7.4 Верифікація 3д карти (PortmoneWebView)
Виклик методу on3dVerificationNeeded з PayeePaymentListener означає, що для проведення оплати даною картою необхідна 3д верифікація, яка відбувається за допомогою PortmoneWebView.
Об’єкт PortmoneWebView, як і будь-який View елемент можна створити 2 способами:
- cтворити як елемент в *.xml файлі:
<com.portmone.sdk.util.PortmoneWebView
android:id="@+id/portmone_web_view"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
- створити програмно об’єкт та додати його до контейнера:
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);
}
Для проведення верифікації необхідно створити та ініціалізувати об’єкт PortmoneWebView та викликати метод setVerify3dData.
Параметри методу setVerify3dData
Параметр | Тип | Опис |
---|---|---|
transaction | PayeePaymentTransaction | Об’єкт транзакції, отриманий з PayeePaymentListener.on3dVerificationNeeded() |
listener | Verify3dListener | Асинхронний колбек з результатом верифікації. |
Verify3dListener
void onVerify3dSuccess(PayeePaymentTransaction transaction);
void onReceivedError(
final WebView view,
final WebResourceRequest req,
final WebResourceError resourceError
);
void onError(Throwable error);
Методи Verify3dListener
Метод | Параметри | Опис |
---|---|---|
onVerify3dSuccess | paymentTransaction: PayeePaymentTransaction | Викликається в разі успішного завершення верифікації та успішного проведення оплати |
onReceivedError | - | Стандартний колбек з помилкою з WebViewClient. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
8. Поповнення мобільного (TopUpMobileService)
Сервіс дозволяє здійснювати поповнення мобільного.
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
Поле | Тип | Опис | Nullability |
---|---|---|---|
card | MasterpassCard | Об’єкт карти мастерпасу отрманої за допомогою CardService.getCards(); | Nonnull |
billAmount | float | Сума до оплати. | Nonnull |
phoneNumber | String | Номер телефону на який здійснюється поповнення. | Nonnull |
commission | float | Комісія для поточного платежу. | Nonnull |
payeeId | String | Ід компанії в системі Portmone. | Nonnull |
bill | Bill | Об’єкт з інформацією про здійснену оплату, заповнюється після успішного завершення оплати. | Nullable |
Об’єкт Bill
Поле | Тип | Опис | Nullability |
---|---|---|---|
billId | String | Унікальне ід здійсненої оплати. | Nullable |
recieptUrl | String | Посилання на pdf з квитанцією. | Nullable |
contractNumber | String | Номер особового рахунку. | Nullable |
payDate | long | Час здійсненої оплати в мілісекундах. | Nullable |
8.1 Отримання комісії (getCommission)
Для здійснення оплати першим кроком є отримання комісії для даного платежу. Об’єкт TopUpMobileTransaction отриманий в результаті успішного отримання комісії необхідний для подальшого здійснення оплати.
Параметри методу getCommission
Параметр | Тип | Опис |
---|---|---|
commissionParams | CommissionParams | Набір параметрів необхідних для отримання комісії. |
phoneNumber | String | Номер телефону на який відбувається поповнення |
listener | CommissionListener | Асинхронний колбек з результатом отримання комісії. |
Об’єкт CommissionParams
Поле | Тип | Опис | Nullability |
---|---|---|---|
card | MasterpassCard | Об’єкт карти мастерпасу отрманої за допомогою CardService.getCards(); | Nonnull |
billAmount | float | Сума до оплати, не повинна бути меншою 0. | Nonnull |
merchantLogin | String | Логін для оплати даної компанії | Nonnull |
billNumber | String | Унікальний згенерований номер рахунку. | Nonnull |
CommissionListener
void onCommissionSuccess(TopUpTransaction paymentTransaction);
void onError(Throwable throwable);
Методи CommissionListener
Метод | Параметри | Опис |
---|---|---|
onCommissionSuccess | paymentTransaction: TopUpMobileTransaction | Об’єкт транзакції. Повертається в разі успішного отримання комісії |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
8.2 Проведення оплати (proceedPayment)
Параметри методу proceedPayment
Параметр | Тип | Опис |
---|---|---|
transaction | TopUpMobileTransaction | Об’єкт транзакції, отриманий з CommissionListener.onCommissionSuccess() |
listener | TopUpMobilePaymentListener | Асинхронний колбек з результатом проведення оплати. |
TopUpMobilePaymentListener
void onPaymentSuccess(TopUpMobileTransaction transaction);
void on2dVerificationNeeded(TopUpMobileTransaction transaction);
void on3dsVerificationNeeded(TopUpMobileTransaction transaction);
void onError(Throwable error);
Методи TopUpMobilePaymentListener
Метод | Параметри | Опис |
---|---|---|
onPaymentSuccess | paymentTransaction: TopUpMobileTransaction | Викликаєтся в разі успішного проведення оплати. Транзакнція заповнена об’єктом Bill. |
on2dVerificationNeeded | paymentTransaction: TopUpMobileTransaction | Викликається в разі необхідності 2д верифікації карти. |
on3dVerificationNeeded | paymentTransaction: TopUpMobileTransaction | Викликається в разі необхідності 3д верифікації карти. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
8.3 Верифікація 2д карти (start2dVerification, finish2dVerification)
Проведення 2д верифікації відбувається в 2 етапи. Перший відбувається при виклику start2dVerification, де відбувається перевірка та валідація карти, після його успішного завершення на номер телефону прив’язаного до карти прийде смс з кодом верифікації, який необхідний для finish2dVerification. При успішному результаті останнього оплата успішно завершується.
Параметри методу start2dVerification
Параметр | Тип | Опис |
---|---|---|
transaction | TopUpMobileTransaction | Об’єкт транзакції, отриманий з TopUpMobilePaymentListener..on2dVerificaitonNeeded() |
cvv | String | Cvv код карти, якій необхідна верифікація. |
listener | Start2dListener | Асинхронний колбек з результатом початку верифікації. |
Start2dListener
void onStart2dSuccess(TopUpMobileTransaction transaction);
void onError(Throwable error);
Методи Start2dListener
Метод | Параметри | Опис |
---|---|---|
onStart2dSuccess | paymentTransaction: TopUpMobileTransaction | Викликаєтся в разі успішного початку 2д верифікації. На номер телефону відсилається смс з кодом для верифікації. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
Параметри методу finish2dVerification
Параметр | Тип | Опис |
---|---|---|
transaction | TopUpMobileTransaction | Об’єкт транзакції, отриманий з Start2dListener.onStart2dSuccess() |
verificationCode | String | Код верифікації отриманий в смс. |
listener | Verify2dListener | Асинхронний колбек з результатом верифікації. |
Verify2dListener
void onVerify2dSuccess(TopUpMobileTansaction transaction);
void onError(Throwable error);
Методи Verify2dListener
Метод | Параметри | Опис |
---|---|---|
onVerify2dSuccess | paymentTransaction: TopUpMobileTransaction | Викликаєтся в разі успішного завершення верифікації та успішного проведення оплати |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
8.4 Верифікація 3д карти (PortmoneWebView)
Виклик методу on3dVerificationNeeded з PayeePaymentListener означає, що для проведення оплати даною картою необхідна 3д верифікація, яка відбувається за допомогою PortmoneWebView.
Об’єкт PortmoneWebView, як і будь який View елемент можна створити 2 способами:
- cтворити як елемент в *.xml файлі:
<com.portmone.sdk.util.PortmoneWebView
android:id="@+id/portmone_web_view"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
- створити програмно об’єкт та додати його до контейнера:
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);
}
Для проведення верифікації необхідно створити та ініціалізувати об’єкт PortmoneWebView та викликати метод setVerify3dData.
Параметри методу setVerify3dData
Параметр | Тип | Опис |
---|---|---|
transaction | TopUpMobileTransaction | Об’єкт транзакції, отриманий з TopUpMobilePaymentListener.on3dVerificationNeeded() |
listener | Verify3dListener | Асинхронний колбек з результатом верифікації. |
Verify3dListener
void onVerify3dSuccess(TopUpMobileTransaction transaction);
void onReceivedError(
final WebView view,
final WebResourceRequest req,
final WebResourceError resourceError
);
void onError(Throwable error);
Методи Verify3dListener
Метод | Параметри | Опис |
---|---|---|
onVerify3dSuccess | paymentTransaction: TopUpMobileTransaction | Викликається в разі успішного завершення верифікації та успішного проведення оплати |
onReceivedError | - | Стандартний колбек з помилкою з WebViewClient. |
onError | throwable:Throwable | Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. |
9. Список можливих помилок
Внутрішні помилки SDK
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, у тому ж форматі.
Помилки Masterpass
Помилки сервісу Portmone та Masterpass передаватимуться за допомогою об’єкту PMError, який є наслідником класу Throwable.
Об’єкт PMError
Поле | Тип | Опис | Nullability |
---|---|---|---|
code | int | Код помилки | Nonnull |
message | String | Опис помилки | Nonnull |