Portmone eCommerce Android SDK

Терміни та визначення

Термін	Визначення
Мерчант, Інтернет-магазин або Партнер	Організація, що уклала договір з Portmone.com про надання послуг з приймання платежів
Покупець, Клієнт	Відвідувач Інтернет-магазину Мерчанта з метою ознайомлення з асортиментом товарів (послуг) та здійснення покупки
Картка, Платіжна картка	Платіжні картки міжнародних платіжних систем Visa, Mastercard та Національної платіжної системи ПРОСТІР
Токен	Цифровий ідентифікатор картки, що генерується при першій операції і далі використовується для швидкої оплати
CVV2/CVC2	CVV2 (Card Verification Value 2) – тризначний код перевірки дійсності картки платіжної системи Visa. Платіжна система MasterCard має аналогічний код перевірки дійсності – CVC2 (Card Validation Code 2)
Авторизація	Процедура отримання підтвердження від банка-емітента на проведення операції оплати карткою
Біометрична авторизація	Процес підтвердження платежу за допомогою технології ідентифікації біометричних даних (відбитків пальців)
Банк-емітент банківських карток	Банк, що є учасником платіжної системи та здійснює випуск (емісію) та обслуговування банківських карток
3-D Secure	3-D Secure – це протокол, який використовувався для забезпечення додаткового рівня безпеки онлайн-платежів з використанням банківських карток

Загальний опис

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

Інтеграція

build.gradle (project level)

allprojects {
   repositories {
       google()
       jcenter()

       mavenCentral()
       maven {
           url "https://github.com/Portmone/Android-e-Commerce-SDK/raw/master/"
       }

   }
}

build.gradle (app level)

dependencies {
       implementation 'com.portmone.ecomsdk:ecomsdk:1.3.4'
}

У SDK прописана логіка, що дозволяє при необхідності безпечно вилучити із залежностей card_io бібліотеку (функція доступна з версії 1.3.0 SDK).

build.gradle (app level)

dependencies {
       implementation ('com.portmone.ecomsdk:ecomsdk:1.3.4'){
            exclude group: 'io.card'
       }
}

В такому випадку із UI SDK буде прибрано функціонал сканування карток, що в свою чергу дасть виграш у зменшенні розміру додатку.

Якщо використовуєте proguard потрібно дадати наступний рядок: keep class com.portmone.ecomsdk.** { *; }

Сценарії використання

1. Оплата карткою.
2. Збереження картки.
3. Оплата за токеном (токен картки може бути отриманий за сценарієм 1 або 2).
4. Переказ коштів з картки на картку за токеном картки відправника.
5. Оплата з підтвердженням відбитком пальця.
6. Оплата з використанням Google Pay.

Опис програмного інтерфейсу

1. Встановлення мови

SDK надає можливість локалізації системного тексту та відповідей з сервера за допомогою методу:

PortmoneSDK.setLanguage(languageСode);

Метод приймає в папарметрах константу з класу Constant$Language.* і може встановлювати українську, англійську або російську мови. У випадку, якщо ця функція не була викликана, буде використовуватись мова, що встановлена на рівні системи. У випадку не знаходження перекладів відповідно до мови системи, буде використовуватись українська мова.

2. Стилізація екранів

Для екранів, які використовуються в SDK, передбачена можливість брендування: зміна кольорів елементів та шрифту, а також кольору текстів. Для цього використовується клас AppStyle. Клас містить набір параметрів, що відповідають за певні елементи на екранах. Можуть бути заповнені тільки потрібні параметри. Всі кольори задаються у форматі hex.

Для задання стилів використовується функція:

PortmoneSDK.setAppStyle(...);

Вказані стилі зберігатимуться до завершення роботи додатку.

App style

Поле	Тип	Опис
background	int	Колір заднього фону екранів
toolbar	int	Колір панелі інструментів на всіх екранах
iconSuccess	int	Дозволяє змінити іконку успішної оплати (доступна з версії 1.2.1 SDK)
iconError	int	Дозволяє змінити іконку неуспішної оплати (доступна з версії 1.2.1 SDK)
type	Constant$Type.*	Цей параметр встановлюється за допомогою значень, які знаходяться у файлі Constant$Type. Можливі три варіанти: 1. Default – стандартний варіант; 2. Phone – відбувається заміна текста заголовка опису “Опис замовлення” на “Номер телефону”, а також до самого значення опису додається “+380” (доступна з версії 1.2.1 SDK) 3. Account – відбувається заміна текста заголовка опису “Опис замовлення” на “Номер особового рахунку” (доступна з версії 1.3.3 SDK)
buttonStyle	ButtonStyle	Містить колір тексту кнопки та заднього фону в звичайному та натиснутому станах, шрифт для тексту кнопки, а також величину заокруглення кнопок
editTextStyle	EditTextStyle	Використовується для полей вводу тексту. Дозволяє змінювати колір основного тексту, тексту підказки та помилки, а також відповідні шрифти
blockTitleTextStyle	BlockTitleTextStyle	Використовується для заголовків блоків на екранах. Дозволяє вказувати колір фону, тексту та шрифт
titleTextStyle	TitleTextStyle	Дозволяє вказувати колір та шрифт заголовків на екранах
descriptionTextStyle	TextStyle	Дозволяє вказувати колір та шрифт основних текстів на екранах
additionalInfoTextStyle	TextStyle	Дозволяє вказувати колір та шрифт додаткових текстів на екранах
fingerprintButton	TextStyle	Дозволяє вказувати колір та шрифт тексту кнопки оплати за допомогою відбитку пальця (доступна з версії 1.1.4 SDK)
paymentSuccessDownload	TextStyle	Дозволяє вказувати колір та шрифт тексту кнопки збереження квитанції на екрані успішної оплати (доступна з версії 1.2.1 SDK)
dialogInfoStyle	DialogInfoStyle	Дозволяє вказувати колір та шрифт заголовку, тексту та тексту кнопки у діалогових вікнах
paymentDivider	TextStyle	Колір текстового розділювача поміж видами оплат (Google Pay та картка)

3. Встановлення кастомного UID

(* функція доступна з версії 1.3.0 SDK)

SDK надає можливість встановити власний UID (ідентифікатор каналу продажів для спецналаштувань, встановлюється за погодженням з менеджером Portmone.com). Для цього слід використати статичний метод із SDK:

PortmoneSDK.setUid("customUID");

UID (shop_site_ID). У разі відсутності UID не передавати значення.

4. Підтвердження оплати відбитком пальця

(* функція доступна з версії 1.1.4 SDK)

SDK надає можливість здійснювати оплату за токеном з використанням сканування відбитку пальця для підтвердження оплати. Для увімкнення цієї можливості потрібно використати:

PortmoneSDK.setFingerprintPaymentEnable(true);

Однак ця можливість недоступна для переказу з токена на картку.

SDK перевіряє наявність фізичного сканера біометрії та збереженого відбитку, у разі їх відсутності ця функція працювати не буде.

Зверніть увагу - для того, щоб увімкнути можливість біометричної авторизації, необхідно надіслати відповідного листа з зареєстрованої адреси електронної пошти менеджерам Portmone.com по співпраці на адресу [email protected].

5. Оплата карткою

5.1. Ініціалізація оплати карткою

Відкрити екран оплати, створений на рівні SDK (CardPaymentActivity), можна двома способами:

1. за допомогою статичного методу performTransaction;
2. за допомогою Activity Result APIs.

5.1.1. Метод performTransaction

Цей метод є перевантаженим і дозволяє приймати Activity або Fragment.

Для отримання Bill про оплату необхідно реалізувати callback onActivityResult, в якому ідентифікувати потрібний результат за допомогою переданого requestCode.

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

Параметр	Тип	Опис	Приклад
activity/fragment	Activity/Fragment	Об’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCode	int	Унікальний код для ідентифікації результату проведеної оплати, необхідний для callback onActivityResult	123
paymentParams	PaymentParams	Набір параметрів, необхідних для проведення оплати
showReceiptScreen	boolean	Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)
returnToDetailsAfterErrorEnabled	boolean	Параметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false) (* параметр доступний з версії 1.3.4 SDK)

Об’єкт PaymentParams

Поле	Тип	Опис	Nullability
payeeId	String	Унікальний ідентифікатор компанії-отримувача в системі Portmone	Nonnull
billNumber	String	Унікальний номер платежу	Nullable
preAuth	boolean	Оплата з преавторизацією. Якщо не встановлено значення – false	Nullable
billCurrency	String	Валюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, BYN, KZT	Nullable
attribute1	String	Атрибут оплати 1	Nullable
attribute2	String	Атрибут оплати 2	Nullable
attribute3	String	Атрибут оплати 3	Nullable
attribute4	String	Атрибут оплати 4	Nullable
attribute5	String	Атрибут оплати 5. Використовується для передачі параметрів розщеплення платежу (детальний опис процедури наведений у розділі «Розщеплення платежу»)	Nullable
billAmount	double	Сума платежу	Nonnull
description	String	Опис платежу	Nullable
onlyGooglePay	boolean	Для оплат виключно через Google Pay	Nullable
testEnvironment	boolean	Використання тестового середовища для Google Pay	Nullable

Примітка: поля attribute 1-5 – необов’язкові поля для додаткових даних, необхідних при оплаті.

Приклад:

final PaymentParams testParamsWithoutGooglePay = new PaymentParams(
     "1234",
     "test bill number",
     true,
     Constant$BillCurrency.UAH,
     "test description",
     "1",
     "2",
     "3",
     "4",
     "5",
     123.45
);

final PaymentParams testParamsWithGooglePay = new PaymentParams(
     "1234",
     "test bill number",
     true,
     Constant$BillCurrency.UAH,
     "test description",
     "1",
     "2",
     "3",
     "4",
     "5",
     123.45,
     false,
     false
);


CardPaymentActivity.performTransaction(
     this,
     111,
     testParamsWithGooglePay,
     false
);

Мал. 1a. Приклад відображення екрану оплати карткою (без стилізації)

Мал. 1б. Приклад відображення екрану оплати карткою (без стилізації)

Мал. 2a. Екран оплати карткою (приклад стилізації)

Мал. 2б. Екран оплати карткою (приклад стилізації)

5.1.2. Метод Activity Result APIs

Необхідно зареєструвати callback, викликавши метод registerForActivityResult, який приймає такі параметри:

• CardPaymentContract;
• ActivityResultCallback.

В ActivityResultCallback потрібно викликати метод handleResult, за допомогою якого можна опрацювати успішний, помилковий результати оплати чи скасування оплати.

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

Параметр	Тип	Опис
successHandler	PaymentResultHandler.Success	Callback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandler	PaymentResultHandler.Failure	Callback для опрацювання помилкового результату
cancelHandler	PaymentResultHandler.Cancel	Callback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

Для запуску 'CardPaymentActivity' необхідно викликати метод launch, передавши в параметрах CardPaymentContractParams.

Об’єкт CardPaymentContractParams

Параметр	Тип	Опис	Nullability
paymentParams	CardPaymentParams	Набір параметрів, необхідних для проведення оплати	Nonnull
showReceiptScreen	boolean	Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)	Optional
returnToDetailsAfterErrorEnabled	boolean	Parameter with which you can prevent the return to the entry of details after an error (default false)(* option available from SDK version 1.3.4)	Optional

Приклад:

private ActivityResultLauncher<CardPaymentContractParams> resultLauncher = registerForActivityResult(
    new CardPaymentContract(),
    result ->
        result.handleResult(
               (successResult) -> { 
                      handleBill(successResult.getBill()); 
                 },
             (failureResult) -> {
                      handleError(
                           failureResult.getCode(),
                           failureResult.getMessage()
                      );
                 },
                 () -> {
                      handlePaymentCancel();
                 }
            )
    );

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
      …
      payButton.setOnClickListener ( 
            button -> resultLauncher.launch(
                         new CardPaymentContractParams(
                             cardPaymentParams,
                               true,
                             false
                         )
            )
      );
}

5.2. Отримання результату оплати

Після проведення успішної оплати буде сформований об’єкт Bill з даними про неї.

6. Збереження картки

Механізм збереження картки дозволяє отримати токен для подальшої оплати цією карткою без вказання номеру та дати. Для отримання токену на картковому рахунку клієнта блокується 1 гривня (розблокування відбувається автоматично протягом 30 хвилин).

6.1. Ініціалізація збереження картки

Відкрити екран оплати, створений на рівні SDK (PreauthCardActivity), можна двома способами:

1. за допомогою статичного методу performTransaction;
2. за допомогою Activity Result APIs.

6.1.1. Метод performTransaction

Цей метод є перевантаженим і дозволяє приймати Activity або Fragment.

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

Параметр	Тип	Опис	Приклад
activity/fragment	Activity/Fragment	Об’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCode	int	Унікальний код для ідентифікації результату проведеної оплати	123
params	SaveCardParams	Набір параметрів, необхідних для збереження картки

Об’єкт SaveCardParams

Поле	Тип	Опис	Nullability
payeeId	String	Унікальний ідентифікатор компанії-отримувача в системі Portmone	Nonnull
billNumber	String	Унікальний номер платежу	Nullable
description	String	Опис платежу	Nullable

Приклад:

final SaveCardParams testParams = new SaveCardParams(
     "1111",
     "test description",
     "test bill number"
);

PreauthCardActivity.performTransaction(
     this,
     113,
     testParams
);

Мал. 3. Приклад відображення екрану збереження картки (без стилізації)

Мал. 4. Екран збереження картки (приклад стилізації)

6.1.2. Метод Activity Result APIs

Необхідно зареєструвати callback, викликавши метод registerForActivityResult, який приймає такі параметри:

• PreauthCardContract;
• ActivityResultCallback.

В ActivityResultCallback потрібно викликати метод handleResult, за допомогою якого можна опрацювати успішний, помилковий результати оплати чи скасування оплати.

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

Параметр	Тип	Опис
successHandler	PaymentResultHandler.Success	Callback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandler	PaymentResultHandler.Failure	Callback для опрацювання помилкового результату
cancelHandler	PaymentResultHandler.Cancel	Callback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

Для запуску 'PreauthCardActivity' необхідно викликати метод launch, передавши в параметрах SaveCardParams.

Об’єкт SaveCardParams

Параметр	Тип	Опис	Nullability
paymentParams	SaveCardParams	Набір параметрів, необхідних для збереження карти	Nonnull

Приклад:

private ActivityResultLauncher<SaveCardParams> resultLauncher = registerForActivityResult(
    new PreauthCardContract(),
    result ->
        result.handleResult(
             (successResult) -> { 
                      handleBill(successResult.getBill()); 
                 },
             (failureResult) -> {
                      handleError(
                           failureResult.getCode(),
                           failureResult.getMessage()
                      );
                 },
                 () -> {
                      handlePaymentCancel();
                 }
            )
    );

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
      …
      payButton.setOnClickListener ( 
            button -> resultLauncher.launch(
                         new SaveCardParams(
                                  "1111",
                                  "test description",
                                  "test bill number"
                         )
            )
      );
}

6.2. Отримання результату збереження

Після проведення успішної оплати буде сформований об’єкт Bill з даними про неї.

Об’єкт Bill

Поле	Тип	Опис	Nullability
billId	String	Ідентифікатор здійсненої оплати	Nonnull
cardMask	String	Маска картки, яка була використана для оплати, з першими шістьма та останніми чотирма цифрами номеру картки	Nonnull
payDate	long	Час здійсненої оплати в мілісекундах	Nullable
payeeName	String	Назва компанії, на яку проводилась оплата	Nullable
token	String	Токен проведеної оплати	Nullable

7. Оплата за токеном

Для здійснення оплати використовується токен, що отриманий одним з двох способів:

1) у відповіді після успішної оплати (див. п. 10.1 "Отримання результатів після закриття SDK");

2) окремим методом збереження картки (див. п. 6 "Збереження картки").

7.1. Ініціалізація оплати за токеном

Відкрити екран оплати, створений на рівні SDK (TokenPaymentActivity), можна двома способами:

1. за допомогою статичного методу performTransaction;
2. за допомогою Activity Result APIs.

7.1.1. Метод performTransaction

Цей метод є перевантаженим і дозволяє приймати Activity або Fragment.

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

Параметр	Тип	Опис	Приклад
activity/fragment	Activity/Fragment	Об’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCode	int	Унікальний код для ідентифікації результату проведеної оплати	123
params	TokenPaymentParams	Набір параметрів, необхідних для проведення оплати
showReceiptScreen	boolean	Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)
returnToDetailsAfterErrorEnabled	boolean	Параметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false) (* параметр доступний з версії 1.3.4 SDK)

Об’єкт TokenPaymentParams

Поле	Тип	Опис	Nullability
payeeId	String	Унікальний ідентифікатор компанії-отримувача в системі Portmone	Nonnull
billNumber	String	Унікальний номер платежу	Nullable
preAuth	boolean	Оплата з преавторизацією. Якщо не встановлено значення – false	Nullable
billCurrency	String	Валюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, BYN, KZT	Nullable
attribute1	String	Атрибут оплати 1	Nullable
attribute2	String	Атрибут оплати 2	Nullable
attribute3	String	Атрибут оплати 3	Nullable
attribute4	String	Атрибут оплати 4	Nullable
attribute5	String	Атрибут оплати 5. Використовується для передачі параметрів розщеплення платежу (детальний опис процедури наведений у розділі «Розщеплення платежу»)	Nullable
billAmount	double	Сума платежу	Nonnull
cardMask	String	Маска збереженої картки	Nonnull
token	String	Токен збереженої картки	Nonnull
description	String	Опис платежу	Nullable
onlyGooglePay	boolean	Для оплати виключно через Google Pay	Nullable
testEnvironment	boolean	Використання тестового середовища для Google Pay	Nullable

Примітка: поля attribute 1-5 – необов’язкові поля для додаткових даних, необхідних при оплаті.

Приклад:

final TokenPaymentParams testParamsWithoutGooglePay = new TokenPaymentParams(
     "1234",
     "test bill number",
     true,
     Constant$BillCurrency.UAH,
     "test description",
     "attr1",
     "attr2",
     "attr3",
     "attr4",
     "attr5",
     123.45,
     "4444 33** **** 1111",
     "test token"
);

final TokenPaymentParams testParamsWithGooglePay = new TokenPaymentParams(
     "1234",
     "test bill number",
     true,
     Constant$BillCurrency.UAH,
     "test description",
     "attr1",
     "attr2",
     "attr3",
     "attr4",
     "attr5",
     123.45,
     "4444 33** **** 1111",
     "test token",
     false,
     false
);


TokenPaymentActivity.performTransaction(
     this,
     111,
     testParamsWithGooglePay,
     false
);

Мал. 5а. Приклад відображення екрану оплати за токеном/ оплати за допомогою Touch ID (без стилізації)

Мал. 5б. Приклад відображення екрану оплати за токеном/ оплати за допомогою Touch ID (без стилізації)

Мал. 6а. Екран оплати за токеном/ оплати за допомогою Touch ID (приклад стилізації)

Мал. 6б. Екран оплати за токеном/ оплати за допомогою Touch ID (приклад стилізації)

7.1.2. Метод Activity Result APIs

Необхідно зареєструвати callback, викликавши метод registerForActivityResult, який приймає такі параметри:

• TokenPaymentContract;
• ActivityResultCallback.

В ActivityResultCallback потрібно викликати метод handleResult, за допомогою якого можна опрацювати успішний, помилковий результати оплати чи скасування оплати.

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

Параметр	Тип	Опис
successHandler	PaymentResultHandler.Success	Callback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandler	PaymentResultHandler.Failure	Callback для опрацювання помилкового результату
cancelHandler	PaymentResultHandler.Cancel	Callback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

Для запуску 'TokenPaymentActivity ' необхідно викликати метод launch, передавши в параметрах TokenPaymentContractParams.

Об’єкт TokenPaymentContractParams

Параметр	Тип	Опис	Nullability
paymentParams	TokenPaymentParams	Набір параметрів, необхідних для проведення оплати	Nonnull
showReceiptScreen	boolean	Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)	Optional
returnToDetailsAfterErrorEnabled	boolean	Параметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false) (* параметр доступний з версії 1.3.4 SDK)	Optional

Приклад:

private ActivityResultLauncher<TokenPaymentContractParams> resultLauncher = registerForActivityResult(
    new TokenPaymentContract(),
    result ->
        result.handleResult(
             (successResult) -> { 
                      handleBill(successResult.getBill()); 
                 },
             (failureResult) -> {
                      handleError(
                           failureResult.getCode(),
                           failureResult.getMessage()
                      );
                 },
                 () -> {
                      handlePaymentCancel();
                 }
            )
    );

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
      …
      payButton.setOnClickListener ( 
            button -> resultLauncher.launch(
                         new TokenPaymentContractParams(
                               tokenPaymentParams,
                               true,
                               false
                         )
            )
      );
}

7.2. Отримання результату оплати за токеном

Після проведення успішної оплати буде сформований об’єкт Bill з даними про неї.

8. Оплата без підтвердження CVV

(* функція доступна з версії 1.3.3 SDK)

SDK надає можливість здійснювати оплату за токеном без підтвердження CVV для оплат, сума яких є меншою або дорівнює значенню, що задається за допомогою методу setBillAmountWithoutCvvConfirmation.

Наприклад:

PortmoneSDK.setBillAmountWithoutCvvConfirmation(100.0);

Однак ця можливість недоступна для переказу з токена на картку.

Зверніть увагу - для того, щоб увімкнути можливість оплати без введення CVV, необхідно надіслати відповідного листа з зареєстрованої адреси електронної пошти менеджерам Portmone.com по співпраці на адресу [email protected].

9. Переказ з картки на картку за токеном

Використовується для здійснення переказу зі збереженим токеном картки відправника.

9.1. Ініціалізація переказу за токеном

Відкрити екран оплати, створений на рівні SDK (TokenTransferActivity), можна двома способами:

1. за допомогою статичного методу performTransaction;
2. за допомогою Activity Result APIs.

9.1.1. Метод performTransaction

Для проведення переказу необхідно відкрити екран переказу, створений на рівні SDK (TokenTransferActivity), за допомогою статичного методу performTransaction(). Цей метод є перевантаженим і дозволяє приймати Activity або Fragment.

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

Параметр	Тип	Опис	Приклад
activity/fragment	Activity/Fragment	Об’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCode	int	Унікальний код для ідентифікації результату проведеного переказу	123
params	TokenTransferParams	Набір параметрів, необхідних для проведення переказу
showReceiptScreen	boolean	Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)
returnToDetailsAfterErrorEnabled	boolean	Параметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false) (* параметр доступний з версії 1.3.4 SDK)

Об’єкт TokenTransferParams

Поле	Тип	Опис	Nullability
payeeId	String	Унікальний ідентифікатор компанії-отримувача в системі Portmone	Nonnull
attribute2	String	Атрибут оплати 2	Nullable
attribute3	String	Атрибут оплати 3	Nullable
attribute4	String	Атрибут оплати 4	Nullable
billAmount	double	Сума платежу. Якщо параметр не задано, то його можна задати вручну на екрані оплати	Nullable
cardMask	String	Маска збереженої картки	Nonnull
token	String	Токен збереженої картки	Nonnull

Примітка: поля attribute 2-4 – необов’язкові поля для додаткових даних, необхідних при оплаті.

Приклад:

final TokenTransferParams testParams = new TokenTransferParams(
     "1234",
     "attr2",
     "attr3",
     "attr4",
     123.45,
     "4444 33** **** 1111",
     "test token"
);

TokenTransferActivity.performTransaction(
     this,
     111,
     testParams,
     false
);

Мал. 7а. Приклад відображення екрану переказу (без стилізації)

Мал. 7б. Приклад відображення екрану переказу (без стилізації)

Мал. 8а. Екран переказу з токену на номер картки (приклад стилізації)

Мал. 8б. Екран переказу з токену на номер картки (приклад стилізації)

9.1.2. Метод Activity Result APIs

Необхідно зареєструвати callback, викликавши метод registerForActivityResult, який приймає такі параметри:

• TokenTransferContract;
• ActivityResultCallback.

В ActivityResultCallback потрібно викликати метод handleResult, за допомогою якого можна опрацювати успішний, помилковий результати оплати чи скасування оплати.

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

Параметр	Тип	Опис
successHandler	PaymentResultHandler.Success	Callback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandler	PaymentResultHandler.Failure	Callback для опрацювання помилкового результату
cancelHandler	PaymentResultHandler.Cancel	Callback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

Для запуску 'TokenTransferActivity' необхідно викликати метод launch, передавши в параметрах TokenTransferContractParams.

Об’єкт TokenTransferContractParams

Параметр	Тип	Опис	Nullability
paymentParams	CardPaymentParams	Набір параметрів, необхідних для проведення оплати	Nonnull
showReceiptScreen	boolean	Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)	Optional
returnToDetailsAfterErrorEnabled	boolean	Параметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false) (* параметр доступний з версії 1.3.4 SDK)	Optional

Приклад:

private ActivityResultLauncher<TokenTransferContractParams> resultLauncher = registerForActivityResult(
    new TokenTransferContract(),
    result ->
        result.handleResult(
             (successResult) -> { 
                      handleBill(successResult.getBill()); 
                 },
             (failureResult) -> {
                      handleError(
                           failureResult.getCode(),
                           failureResult.getMessage()
                      );
                 },
                 () -> {
                      handlePaymentCancel();
                 }
            )
    );


@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
      …
      payButton.setOnClickListener ( 
            button -> resultLauncher.launch(
                         new TokenTransferContractParams(
                               tokenTransferParams,
                               true,
                               false
                         )
            )
      );
}

9.2. Отримання результату переказу за токеном

Після проведення успішного переказу буде сформований об’єкт Bill з даними про неї.

10. Оплата з використанням Google Pay

(* функція доступна з версії 1.3.0 SDK)

Оплата через Google Pay доступна як додаткова можливість при оплаті карткою та оплаті за токеном.

Для цього в об’єкті PaymentParams/ TokenPaymentParams слід вказати додаткові поля:

Поле	Тип	Опис	Nullability
onlyGooglePay	boolean	Для оплат виключно через Google Pay	Nullable
testEnvironment	boolean	Використання тестового середовища для Google Pay	Nullable

Важливо! Перед релізом додатку необхідно отримати погодження від команди Google. Для цього заповніть форму, завантаживши відео усього процесу вибору методу оплати у вашому додатку або скріншоти, та надішліть до Google для перевірки.

Мал. 9а. Приклад відображення екрану оплати з можливістю оплати карткою або через Google Pay (без стилізації)

Мал. 9б. Приклад відображення екрану оплати з можливістю оплати карткою або через Google Pay (без стилізації)

Мал. 10. Приклад відображення екрану оплати за допомогою Google Pay (без стилізації)

11. Отримання результатів оплати та помилок у випадку неуспіху

11.1. Отримання результатів після закриття SDK

Після проведення успішної оплати буде сформований об’єкт Bill з даними про неї. Цей об’єкт можна отримати після успішного завершення оплати в методі:

onActivityResult(requestCode, resultCode, data)

відповідного Activity, що вказаний при виклику SDK, з відповідним requestCode та resultCode - RESULT_OK. Об’єкт Bill можна отримати з об’єкту data, як Serializable extra за допомогою ключа Constant$ExtraKey.Bill.

Об’єкт Bill

Поле	Тип	Опис	Nullability
billId	String	Ідентифікатор здійсненої оплати	Nonnull
status	String	Статус проведеної оплати. Можливі значення “PAYED” та “PREAUTH”, в залежності від потрібного типу оплати, вибраного під час ініціалізації	Nonnull
billAmount	double	Сума проведеної оплати	Nonnull
commissionAmount	double	Комісія проведеної оплати	Nullable
cardMask	String	Маска картки, яка була використана для оплати, з першими шістьма та останніми чотирма цифрами номеру картки	Nonnull
recieptUrl	String	Посилання на pdf з квитанцією	Nullable
contractNumber	String	Номер особового рахунку	Nullable
payDate	long	Час здійсненої оплати в мілісекундах	Nullable
payeeName	String	Назва компанії, на яку проводилась оплата	Nullable
token	String	Токен проведеної оплати	Nullable

Також в extra за допомогою ключа Constant$ExtraKey.PAID_WITH_GOOGLE можна отримати boolean значення типу оплати. Якщо true – оплата була через Google Pay і токен такої оплати не можна використовувати для подальшої оплати з використанням токену (збереженої картки).

Якщо оплата не пройшла успішно, то resultCode - RESULT_CANCELED. У випадку, якщо оплата завершилась із помилкою, з extras можна отримати код та текст помилки за ключами Constant$ExtraKey.ERROR_CODE та Constant$ExtraKey.ERROR_MESSAGE відповідно.

Приклад:

@Override
protected void onActivityResult(
     final int requestCode, final int resultCode, @Nullable final Intent data
) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == 111) {
     if (resultCode == RESULT_OK && data != null) {
        Bill bill = (Bill) data.getSerializableExtra(Constant$ExtraKey.BILL);
        Log.d("PaymentActivity", bill.toString());
     } else if (resultCode == RESULT_CANCELED) {
        if (data != null && data.hasExtra(Constant$ExtraKey.ERROR_CODE)) {
           int errorCode = data.getIntExtra(Constant$ExtraKey.ERROR_CODE, -1);
           String errorMessage = data.getStringExtra(Constant$ExtraKey.ERROR_MESSAGE);
           Log.d("PaymentActivity", "error code: " + errorCode + ", errorMessage: " + errorMessage);
        } else {
           //користувач вийшов з sdk без проходження всього flow оплати
        }
     }
   }
}

11.2. Отримання результатів напряму з SDK

(* функція доступна з версії 1.3.0 SDK)

Результат виконання оплати можна отримати одразу по факту оплати не очікуючи закриття SDK та виклику onActivityResult. Для цього слід вказати відповідний статичний Callback в класі PortmoneSDK.

public class PayActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        PortmoneSDK.setPaymentCallback(new PortmoneSDK.PaymentCallback() {
            @Override
            public void paymentSuccess(Bill bill,  boolean paidThroughGooglePay) {
               Log.d(TAG, "paymentSuccess bill = [" + bill + "], withGoogle: " + paidThroughGooglePay);
            }

            @Override
            public void paymentError(int code, String message) {
                Log.d("PayActivity", "paymentError called with: code = [" + code + "], message = [" + message + "]");
            }
        });
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
        PortmoneSDK.setPaymentCallback(null);
    }
}

Коди помилок

Код помилки	Опис
2000	Сума оплати менше 0
2001	Не вказаний payeeId компанії
2002	Номер картки порожній
2004	Не вказаний термін дії картки
2005	Невірний термін дії картки
2006	Помилка верифікації
2007	Помилка отримання комісії
2008	Відсутній код верифікації
2010	Відсутній CVV код
2011	Невірний CVV код
2023	Помилка при оплаті карткою або при додатковій 2д перевірці. Помилка виникає якщо при оплаті статус замовлення не є PAYED або PREAUTH і не потрібна додаткова верифікація, або при 2д верифікації, якщо замовлення також не містить цих статусів

Тестування

Після реєстрації у системі Portmone.com вам необхідно отримати у менеджера по співпраці наступну інформацію:

• ідентифікатор вашої компанії у системі Portmone.com (payee_id);
• приватний ключ вашої компанії, що використовується для формування унікального підпису кожного запиту.

Система Portmone.com надає партнерам можливість використовувати для тестування два режими: тестовий режим та продуктивний режим з автоматичним скасуванням платежів.

Тестовий режим роботи платіжного шлюзу означає, що система Portmone.com виконує усі перевірки коректності введених даних від Партнера та його клієнта, формує замовлення, але авторизація платіжної картки не виконується. Проходження перевірки 3D Secure неможливе.

Картки для тестування:

Номер картки	Результат
4444333322221111	Успішна оплата
4111111111111111	Неуспішна оплата

Продуктивний режим з автоматичним скасуванням оплати дає можливість виконувати реальні оплати з використанням реальних карток. Після здійснення оплати списані кошти повертаються на картку протягом 30 хвилин (відбувається автоматичне скасування платежу).

Для того, щоб увімкнути чи вимкнути тестовий режим платіжного шлюзу або автоматичне скасування платежу, необхідно надіслати відповідного листа з зареєстрованої адреси електронної пошти менеджерам Portmone.com по співпраці з на адресу [email protected].

Важливо! Перед запуском в роботу системи приймання платежів переконайтеся, що тестовий режим або автоматичне скасування платежу відключені!