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 у вашому особистому кабінеті)

Передати інформацію необхідно листом на SDKpartners@portmone.me з темою “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&lt;MasterpassCard&gt; 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
email	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. При успішному результаті останнього оплата успішно завершується.

Верифікація 2д карти

Параметри методу 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.

Верифікація 3д карти

Об’єкт 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д карти

Параметри методу 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)

Верифікація 3д карти

Об’єкт 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);
}

Параметри методу 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

Code	Description
2100	Internal Error
2101	Connection Error
2102	Card Number is empty
2103	Card Number is invalid
2104	Cvv/Cvc2 is empty
2105	Cvv/Cvc2 is invalid
2106	Card Name is empty
2107	Validation Code is empty
2108	Validation Code is invalid
2109	3D Url is empty
2110	3D Secure is not validated
2111	Terms & Condition checkbox is not selected
2112	Expire Year is invalid
2113	OTP sending card's Bank is required.
2114	MasterPass OTP is required for phone number validation.
2200	*Серверна помилка сервісу Masterpass.

Помилки сервісу Portmone та Masterpass передаватимуться за допомогою об’єкту PMError, який є наслідником класу Throwable.

Об’єкт PMError

Поле	Тип	Опис	Nullability
code	int	Код помилки	Nonnull
message	String	Опис помилки	Nonnull