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

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

  • EN
  • UK

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

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

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

Documentation

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

Masterpass Android SDK

Android інтеграція

Portmone SDK підтримує версію Android 4.4 KitKat, API level 19 та пізніші версії.

Можливості, які надає Portmone SDK

Гаманець Masterpass:

  • додавання картки до існуючого гаманця або створення нового;
  • видалення карток з існуючого гаманця;
  • отримання списку карток для існуючого гаманця.

Оплата:

  • поповнення мобільного за допомогою карток Masterpass;
  • оплата послуг за особовим рахунком за допомогою карток Masterpass.

Перед початком роботи

Реєстрація у Masterpass™

Для початку роботи з Masterpass™ необхідно пройти процес merchant-реєстрації на developers.mastercard.com. Для цього:

  1. Перейдіть на https://developer.mastercard.com/account/sign-up
  2. Заповніть анкетні дані та пройдіть процедуру підтвердження e-mail адреси
  3. Створіть проект на сторінці 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
clientIdStringУнікальне ід клієнта в системі мастерпасNonnull
merchantKeyStringУнікальний ключNonnull

3. Авторизація (AuthService)

Для використання можливостей SDK потрібно авторизуватися в системі. Для авторизації використовується AuthService, який отримується за допомогою PortmoneSDK.getAuthService() та його метод authorize. Авторизація для одного користувача зберігається протягом життя додатку після виклику методу. Для зміни користувача потрібно викликати цей метод знову з іншими параметрами.

Під час виклику методу відбувається перевірка статусу гаманця за вказаним номером телефону, в разі необхідності автоматично відбувається лінкування клієнта до системи Masterpass. В такому випадку необхідна верифікація карти за допомогою OTP коду і з’явиться помилка 2113.

Авторизація

AuthService

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

Параметри методу authorize

ПараметрТипОписПриклад
phoneNumberStringНомер телефону користувача. Використовується як ідентифікатор в гаманці Masterpass.“380666789555”
userIdStringІд користувача в Portmone. Потрібен для ідентифікації в системі Portmone.“3715100”
loginListenerLoginListenerАсинхронний колбек з результатом авторизації.

Отримання результату авторизації:

LoginListener

void onSuccess();

void onError(Throwable throwable);

Методи LoginListener

МетодПараметриОпис
onSuccessВикликається після успішній авторизації в системі
onErrorthrowable: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

ПараметрТипОписПриклад
cardNumberMasterPassEditTextНомер картки заповнений у об’єкті 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() заборонені. Їх виклик призводить до помилки.
Див. нижче
expireMonthintМісяць терміну дії картки12
expireYearintРік терміну дії картки2020 або 20
cardNameStringУнікальне ім’я карти в гаманці“Card Name”
cvvMasterpassEditTextCVV код картки заповнений у об’єкті MasterpassEditText.
Наступні параметри повинні бути вказані
xmlns:masterpass=
"http://schemas.android.com/apk/res-auto"
аndroid:inputType="number"
android:maxLength="4"
masterpass:type="3"
Методи getText() та setText() заборонені. Їх виклик призводить до помилки.
Див. нижче
termsConditionsCheckBoxПідтвердження погодження з правилами Masterpass
addCardListenerAddCardListenerАсинхронний колбек з додавання карти.

Приклад параметру 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Викликається після успішного додавання картки.
onErrorthrowable: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

МетодПараметриОпис
getFirstCharfirstChar:charВикликається при введенні першого символу номеру картки і його ж повертає як параметр.
getFirst6Charsdigits:StringВикликається при введенні перших 6 символів номеру картки і їх ж повертає як параметр.
cancelInstallmentВикликається при видаленні усіх символів.

4.2 Отримання списку карток (getMasterpassCards)

Метод дозволяє отримати список існуючих карток для гаманця за номером телефону вказаному при AuthService#authorize.

Отримання списку карток

Параметри методу getMasterpassCards

ПараметрТипОписПриклад
getCardsListenerGetCardsListenerАсинхронний колбек з результатом отримання карток

GetCardsListener

void onSuccess(final List&lt;MasterpassCard&gt; cards)

void onError(final Throwable throwable)

Методи GetCardsListener

МетодПараметриОпис
onSuccesscards:List<MasterpassCard>Викликається після успішного отримання карток. При успішному запиті метод повертає список об’єктів MasterpassCard.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

Об‘єкт MasterpassCard

ПолеТипОписNullability
maskedPanStringЗамаскований номер картки у форматі 444433********11.Nonnull
nameStringУнікальна назва картки в гаманці 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

ПараметрТипОписПриклад
cardNameStringНазва картки в системі Masterpass. Отримується з MasterpassCard#getName()“Card name”
listenerDeleteCardListenerАсинхронний колбек з результатом видалення

DeleteCardsListener

void onSuccess()

void onError(Throwable throwable)

Методи DeleteCardsListener

МетодПараметриОпис
onSuccessВикликається після успішного видалення картки.
onErrorthrowable: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

ПараметрТипОпис
codeMasterPassEditTextОб’єкт MasterpassEditText з заповненим кодом для валідації. Наступні атрибути повинні бути вказані:
xmlns:masterpass="http://schemas.android.com/apk/res-auto"
android:inputType="numberPassword" android:maxLength="6"
masterpass:type="4"
listenerValidateCodeListenerАсинхронний колбек з результатом перевірки.

Приклад параметру 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Викликається після успішної валідації.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError. Можливі помилки 2113 і 2114, при який необхідна OTP валідація.

6. Отримання компаній (PayeeService)

Сервіс дозволяє отримати компанії на які можна здійснювати оплату за допомогою SDK. Об’єкт отримується за допомогою PortmoneSDK.getPayeeService().

PayeeService

void getPayees(GetPayeeListener getPayeeListener);

Параметри методу getPayees

ПараметрТипОписПриклад
listenerGetPayeeListenerАсинхронний колбек з результатом отримання компаній.

GetPayeeListener

void onSuccess(List<Payee> payees);

void onError(Throwable throwable);

Методи GetPayeeListener

МетодПараметриОпис
onSuccesspayees: ListВикликається після успішного отримання списку компаній.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

Об’єкт Payee

ПолеТипОписNullability
payeeIdStringУнікальне ід компаніїNonnull
nameStringНазва компанії.Nonnull
contractNumberTitleHashMap<String,String>Назва номеру рахунку. Містить переклади на 3 мовах за ключами:
“uk ” - українська,
“en” = англійська,
“ru” = російська
Nonnull
contractNumberTypeStringТип даних для номеру рахунку. Можливі значення:
“N” - число,
“C” - текст,
“D” - дата у фоматі "dd.MM.yyyy".
Nonnull
contractNumberSizeStringМаксимальний розмір поля.Nullable
attribute1TitleHashMap<String,String>Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” - українська , “en” = англійська, “ru” = російськаNullable
attribute1TypeStringТип даних для атрибуту. Можливі значення:
“N” - число,
“C” - текст,
“D” - дата у фоматі "dd.MM.yyyy".
Nullable
attribute1SizeStringМаксимальний розмір поля.Nullable
attribute1ForInfobooleanПри значенні true означає що поле не має бути показанеNullable
attribute2TitleHashMap<String,String>Назва атрибуту. Містить переклади на 3 мовах за ключами:
“uk ” - українська,
“en” = англійська,
“ru” = російська
Nullable
attribute2TypeStringТип даних для атрибуту. Можливі значення:
“N” - число,
“C” - текст,
“D” - дата у фоматі "dd.MM.yyyy".
Nullable
attribute2SizeStringМаксимальний розмір поля.Nullable
attribute2ForInfobooleanПри значенні true означає що поле не має бути показанеNullable
attribute3TitleHashMap<String,String>Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” - українська , “en” = англійська, “ru” = російськаNullable
attribute3TypeStringТип даних для атрибуту. Можливі значення:
“N” - число,
“C” - текст,
“D” - дата у фоматі "dd.MM.yyyy".
Nullable
attribute3SizeStringМаксимальний розмір поля.Nullable
attribute3ForInfobooleanПри значенні true означає що поле не має бути показанеNullable
attribute4TitleHashMap<String,String>Назва атрибуту. Містить переклади на 3 мовах за ключами:
“uk ” - українська,
“en” = англійська,
“ru” = російська
Nullable
attribute4TypeStringТип даних для атрибуту. Можливі значення:
“N” - число,
“C” - текст,
“D” - дата у фоматі "dd.MM.yyyy".
Nullable
attribute4SizeStringМаксимальний розмір поля.Nullable
attribute4ForInfobooleanПри значенні true означає що поле не має бути показанеNullable
imageUrlStringUrl з зображенням для даної компаніїNullable
needRedirectbooleanВизначає чи потрібен перехід на сайт для оплати даної компаніїNonnull
gatewayHashMap<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
cardMasterpassCardОб’єкт карти мастерпасу отриманої за допомогою CardService.getCards();NonNull
billAmountfloatСума до оплати.NonNull
payeeIdStringІд компанії в системі Portmone.NonNull
commissionfloatКомісія для поточного платежуNonNull
billBillОб’єкт з інформацією про здійснену оплату, заповнюється після успішного завершення оплати.Nullable

Об’єкт Bill

ПолеТипОписNullability
billIdStringУнікальне ід здійсненої оплати.Nullable
recieptUrlStringПосилання на pdf з квитанцією.Nullable
contractNumberStringНомер особового рахунку.Nullable
payDatelongЧас здійсненої оплати в мілісекундах.Nullable

7.1 Отримання комісії (getCommission)

Для здійснення оплати першим кроком є отримання комісії для даного платежу. Об’єкт PayeePaymentTransaction отриманий в результаті успішного отримання комісії необхідний для подальшого здійснення оплати.

Параметри методу getCommission

ПараметрТипОпис
commissionParamsCommissionParamsНабір параметрів необхідних для отримання комісії.
payeeIdStringІденитфікатор компанії на яку здійснюєтся оплата в системі Портмоне.
listenerCommissionListenerАсинхронний колбек з результатом отримання комісії.

Об’єкт CommissionParams

ПолеТипОписNullability
cardMasterpassCardОб’єкт карти мастерпасу отрманої за допомогою CardService.getCards();Nonnull
billAmountfloatСума до оплати, не повинна бути меншою 0.Nonnull
merchantLoginStringЛогін для оплати даної компаніїNonnull
billNumberStringУнікальний згенерований номер рахунку.Nonnull

CommissionListener

void onCommissionSuccess(PayeePaymentTransaction paymentTransaction);

void onError(Throwable throwable);

Методи CommissionListener

МетодПараметриОпис
onCommissionSuccesspaymentTransaction: PayeePaymentTransactionОб’єкт транзакції. Повертається в разі успішного отримання комісії
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

7.2 Проведення оплати (proceedPayment)

Параметри методу proceedPayment

ПараметрТипОпис
transactionPayeePaymentTransactionОб’єкт транзакції, отриманий з CommissionListener.onCommissionSuccess()
paymentParamsPaymentParamsОб’єкт з набором параметрів необхідних для оплати.
listenerPayeePaymentListenerАсинхронний колбек з результатом проведення оплати.

Об’єкт PaymentParams

ПолеТипОписNullability
contractNumberStringНомер особового рахунку (*)Nonnull
attribute1StringАтрибут оплати 1. (*)Nullable
attribute2StringАтрибут оплати 2. (*)Nullable
attribute3StringАтрибут оплати 3. (*)Nullable
attribute4StringАтрибут оплати 4. (*)Nullable
emailStringЕлектронна пошта, на яку буде вислана квитанція.Nullable

* Поля contractNumber, attribute 1-4 повинні відповідати полям об’єкта Payee і заповнені у відповідному порядку.

PayeePaymentListener

void onPaymentSuccess(PayeePaymentTransaction transaction);

void on2dVerificationNeeded(PayeePaymentTransaction transaction);

void on3dsVerificationNeeded(PayeePaymentTransaction transaction);

void onError(Throwable error);

Методи PayeePaymentListener

МетодПараметриОпис
onPaymentSuccesspaymentTransaction: PayeePaymentTransactionВикликається в разі успішного проведення оплати. Транзакція заповнена об’єктом Bill.
on2dVerificationNeededpaymentTransaction: PayeePaymentTransactionВикликається в разі необхідності 2д верифікації карти.
on3dVerificationNeededpaymentTransaction: PayeePaymentTransactionВикликається в разі необхідності 3д верифікації карти.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

7.3 Верифікація 2д карти (start2dVerification, finish2dVerification)

Проведення 2д верифікації відбувається в 2 етапи. Перший відбувається при виклику start2dVerification, де відбувається перевірка та валідація карти, після його успішного завершення на номер телефону прив’язаного до карти прийде смс з кодом верифікації, який необхідний для finish2dVerification. При успішному результаті останнього оплата успішно завершується.

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

Параметри методу start2dVerification

ПараметрТипОпис
transactionPayeePaymentTransactionОб’єкт транзакції, отриманий з PayeePaymentListener..on2dVerificaitonNeeded()
cvvStringCvv код карти, якій необхідна верифікація.
listenerStart2dListenerАсинхронний колбек з результатом початку верифікації.

Start2dListener

void onStart2dSuccess(PayeePaymentTransaction transaction);

void onError(Throwable error);

Методи Start2dListener

МетодПараметриОпис
onStart2dSuccesspaymentTransaction: PayeePaymentTransactionВикликаєтся в разі успішного початку 2д верифікації. На номер телефону відсилається смс з кодом для верифікації.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

Параметри методу finish2dVerification

ПараметрТипОпис
transactionPayeePaymentTransactionОб’єкт транзакції, отриманий з Start2dListener.onStart2dSuccess()
verificationCodeStringКод верифікації отриманий в смс.
listenerVerify2dListenerАсинхронний колбек з результатом верифікації.

Verify2dListener

void onVerify2dSuccess(PayeePaymentTransaction transaction);

void onError(Throwable error);

Методи Verify2dListener

МетодПараметриОпис
onVerify2dSuccesspaymentTransaction: PayeePaymentTransactionВикликаєтся в разі успішного завершення верифікації та успішного проведення оплати
onErrorthrowable: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

ПараметрТипОпис
transactionPayeePaymentTransactionОб’єкт транзакції, отриманий з PayeePaymentListener.on3dVerificationNeeded()
listenerVerify3dListenerАсинхронний колбек з результатом верифікації.

Verify3dListener

void onVerify3dSuccess(PayeePaymentTransaction transaction);

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

 void onError(Throwable error);

Методи Verify3dListener

МетодПараметриОпис
onVerify3dSuccesspaymentTransaction: PayeePaymentTransactionВикликається в разі успішного завершення верифікації та успішного проведення оплати
onReceivedError-Стандартний колбек з помилкою з WebViewClient.
onErrorthrowable: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
cardMasterpassCardОб’єкт карти мастерпасу отрманої за допомогою CardService.getCards();Nonnull
billAmountfloatСума до оплати.Nonnull
phoneNumberStringНомер телефону на який здійснюється поповнення.Nonnull
commissionfloatКомісія для поточного платежу.Nonnull
payeeIdStringІд компанії в системі Portmone.Nonnull
billBillОб’єкт з інформацією про здійснену оплату, заповнюється після успішного завершення оплати.Nullable

Об’єкт Bill

ПолеТипОписNullability
billIdStringУнікальне ід здійсненої оплати.Nullable
recieptUrlStringПосилання на pdf з квитанцією.Nullable
contractNumberStringНомер особового рахунку.Nullable
payDatelongЧас здійсненої оплати в мілісекундах.Nullable

8.1 Отримання комісії (getCommission)

Для здійснення оплати першим кроком є отримання комісії для даного платежу. Об’єкт TopUpMobileTransaction отриманий в результаті успішного отримання комісії необхідний для подальшого здійснення оплати.

Параметри методу getCommission

ПараметрТипОпис
commissionParamsCommissionParamsНабір параметрів необхідних для отримання комісії.
phoneNumberStringНомер телефону на який відбувається поповнення
listenerCommissionListenerАсинхронний колбек з результатом отримання комісії.

Об’єкт CommissionParams

ПолеТипОписNullability
cardMasterpassCardОб’єкт карти мастерпасу отрманої за допомогою CardService.getCards();Nonnull
billAmountfloatСума до оплати, не повинна бути меншою 0.Nonnull
merchantLoginStringЛогін для оплати даної компаніїNonnull
billNumberStringУнікальний згенерований номер рахунку.Nonnull

CommissionListener

void onCommissionSuccess(TopUpTransaction paymentTransaction);

void onError(Throwable throwable);

Методи CommissionListener

МетодПараметриОпис
onCommissionSuccesspaymentTransaction: TopUpMobileTransactionОб’єкт транзакції. Повертається в разі успішного отримання комісії
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

8.2 Проведення оплати (proceedPayment)

Параметри методу proceedPayment

ПараметрТипОпис
transactionTopUpMobileTransactionОб’єкт транзакції, отриманий з CommissionListener.onCommissionSuccess()
listenerTopUpMobilePaymentListenerАсинхронний колбек з результатом проведення оплати.

TopUpMobilePaymentListener

void onPaymentSuccess(TopUpMobileTransaction transaction);

void on2dVerificationNeeded(TopUpMobileTransaction transaction);

void on3dsVerificationNeeded(TopUpMobileTransaction transaction);

void onError(Throwable error);

Методи TopUpMobilePaymentListener

МетодПараметриОпис
onPaymentSuccesspaymentTransaction: TopUpMobileTransactionВикликаєтся в разі успішного проведення оплати. Транзакнція заповнена об’єктом Bill.
on2dVerificationNeededpaymentTransaction: TopUpMobileTransactionВикликається в разі необхідності 2д верифікації карти.
on3dVerificationNeededpaymentTransaction: TopUpMobileTransactionВикликається в разі необхідності 3д верифікації карти.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

8.3 Верифікація 2д карти (start2dVerification, finish2dVerification)

Проведення 2д верифікації відбувається в 2 етапи. Перший відбувається при виклику start2dVerification, де відбувається перевірка та валідація карти, після його успішного завершення на номер телефону прив’язаного до карти прийде смс з кодом верифікації, який необхідний для finish2dVerification. При успішному результаті останнього оплата успішно завершується.

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

Параметри методу start2dVerification

ПараметрТипОпис
transactionTopUpMobileTransactionОб’єкт транзакції, отриманий з TopUpMobilePaymentListener..on2dVerificaitonNeeded()
cvvStringCvv код карти, якій необхідна верифікація.
listenerStart2dListenerАсинхронний колбек з результатом початку верифікації.

Start2dListener

void onStart2dSuccess(TopUpMobileTransaction transaction);

void onError(Throwable error);

Методи Start2dListener

МетодПараметриОпис
onStart2dSuccesspaymentTransaction: TopUpMobileTransactionВикликаєтся в разі успішного початку 2д верифікації. На номер телефону відсилається смс з кодом для верифікації.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

Параметри методу finish2dVerification

ПараметрТипОпис
transactionTopUpMobileTransactionОб’єкт транзакції, отриманий з Start2dListener.onStart2dSuccess()
verificationCodeStringКод верифікації отриманий в смс.
listenerVerify2dListenerАсинхронний колбек з результатом верифікації.

Verify2dListener

void onVerify2dSuccess(TopUpMobileTansaction transaction);

void onError(Throwable error);

Методи Verify2dListener

МетодПараметриОпис
onVerify2dSuccesspaymentTransaction: TopUpMobileTransactionВикликаєтся в разі успішного завершення верифікації та успішного проведення оплати
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

8.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

ПараметрТипОпис
transactionTopUpMobileTransactionОб’єкт транзакції, отриманий з TopUpMobilePaymentListener.on3dVerificationNeeded()
listenerVerify3dListenerАсинхронний колбек з результатом верифікації.

Verify3dListener

 void onVerify3dSuccess(TopUpMobileTransaction transaction);

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

 void onError(Throwable error);

Методи Verify3dListener

МетодПараметриОпис
onVerify3dSuccesspaymentTransaction: TopUpMobileTransactionВикликається в разі успішного завершення верифікації та успішного проведення оплати
onReceivedError-Стандартний колбек з помилкою з WebViewClient.
onErrorthrowable:ThrowableВикликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт PMError.

9. Список можливих помилок

Внутрішні помилки SDK

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

Також можливі помилки серверу Portmone, у тому ж форматі.

Помилки Masterpass

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

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

Об’єкт PMError

ПолеТипОписNullability
codeintКод помилкиNonnull
messageStringОпис помилкиNonnull
← Masterpass iOS SDKH2H JSON ASYNC для PCI DSS →
  • Android інтеграція
  • Можливості, які надає Portmone SDK
  • Перед початком роботи
    • Реєстрація у Masterpass™
    • Реєстрація у Portmone.com
  • 1. Інтеграція aar
  • 2. Початок роботи з SDK
  • 3. Авторизація (AuthService)
  • 4. Гаманець Masterpass (CardService)
    • 4.1 Додавання картки (addMasterpassCard)
    • 4.2 Отримання списку карток (getMasterpassCards)
    • 4.3 Видалення картки (deleteMasterpassCard)
  • 5. OTP верифікація (validateCode)
  • 6. Отримання компаній (PayeeService)
  • 7. Оплата (PayeePaymentService)
    • 7.1 Отримання комісії (getCommission)
    • 7.2 Проведення оплати (proceedPayment)
    • 7.3 Верифікація 2д карти (start2dVerification, finish2dVerification)
    • 7.4 Верифікація 3д карти (PortmoneWebView)
  • 8. Поповнення мобільного (TopUpMobileService)
    • 8.1 Отримання комісії (getCommission)
    • 8.2 Проведення оплати (proceedPayment)
    • 8.3 Верифікація 2д карти (start2dVerification, finish2dVerification)
    • 8.4 Верифікація 3д карти (PortmoneWebView)
  • 9. Список можливих помилок
Copyright © 2022 Portmone.com