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.0, API level 21 та пізніші версії.

Інтеграція

settings.gradle (project level)

pluginManagement {
   repositories {
       gradlePluginPortal()
       google()
       mavenCentral()
   }
}
dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
       google()
       mavenCentral()
       jcenter()
       maven {
           url "https://github.com/Portmone/Android-e-Commerce-SDK/raw/master/"
       }
   }
}

rootProject.name = "TestSDK_v3" include ':app'

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 через PortmoneSDK.init(this) у Application.onCreate().

public class App extends Application {


    @Override
    public void onCreate() {
        super.onCreate();

        PortmoneSDK.init(this);
    }
}

У версіях SDK до 3.0.11 сканування картки реалізовувалося через бібліотеку card.io і могло бути виключене із залежностей додатку. Починаючи з версії SDK 3.0.11 механізм сканування картки замінено на Google Payment Card Recognition API. Використання або виключення бібліотеки card.io у поточних версіях SDK не застосовується.

Сканування картки (Google Payment Card Recognition API)

Починаючи з версії SDK 3.0.11 у UI SDK доступне сканування картки на основі Google Payment Card Recognition API. Функціонал є опційним: якщо необхідні налаштування не виконані, кнопка/іконка «Сканувати картку» в інтерфейсі SDK не відображатиметься або не працюватиме.

Налаштування Google Payment Card Recognition (для користувачів SDK)

Google Cloud Console
Створіть або оберіть існуючий Google Cloud Project.
Переконайтесь, що у верхній панелі вибрано правильний проєкт.
Увімкніть Google Wallet API
Перейдіть у APIs & Services → Library.
Знайдіть Google Wallet API та натисніть Enable.
Створіть OAuth 2.0 Client ID для Android
Перейдіть у APIs & Services → Credentials.
Оберіть Create Credentials → OAuth client ID.
Тип застосунку: Android.

Вкажіть:
- Package name вашого застосунку
- SHA-1 сертифіката підпису

Примітка:
У поточній реалізації SDK сканування може відображатися або працювати лише для release-збірки (потрібен SHA-1 релізного підпису).
Функціонал доступний на пристроях із Google Play Services.

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

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

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

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

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

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

PortmoneSDK.setLanguage(languageСode);

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

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

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

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

PortmoneSDK.setAppStyle(...);

Починаючи з версії 3.0.15 метод викликається з додатковим параметром:

PortmoneSDK.setAppStyle(appStyle, true);

Значення параметра: true — стилі зберігаються між перезапусками застосунку. false — стилі застосовуються лише під час поточної роботи застосунку.

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 та картка)
googlePayButtonTheme	Auto / Light / Dark	Налаштування кольору кнопки Google Pay, за замовчуванням Auto. (доступна з версії 3.0.15 SDK)

З версії 2.2.5 SDK доступні такі властивості стилів та невелика зміна логіки екранів:

PortmoneSDK.setStandartResultFlow(false); - дозволяє відключити екрани про результат операції з боку SDK. Тоді результат можна обробити - дивись пункт 11.2

PortmoneSDK.setAdditionalCustomize(true); - додаткова кастомізація екранів для зберігання картки та оплати карткою.

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

Збереження картки метод PreAuthCardPreActivity

Стандартний текст

PortmoneSDK.setDescriptionSaveCard("");
PortmoneSDK.setTitleSaveCard("");

Без тексту

PortmoneSDK.setDescriptionSaveCard(" ");
PortmoneSDK.setTitleSaveCard(" ");

Кастомний текст

PortmoneSDK.setDescriptionSaveCard("Збережи картку");
PortmoneSDK.setTitleSaveCard("Хочешь 100 млн грн?");

Збереження картки метод PreAuthCardPreActivity та оплату карткою метод CardActivity

PortmoneSDK.setNameCompany("PORTMONE"); - вcтановлення назви компанії. PortmoneSDK.setUAHSymbol(true); - встановлення знаку грн, заміст грн після сумми.

appStyle.setIconPayment(R.drawable.ic_portmone);- можна встановити іконку компанії.

Нова стилизація полів вводу:

Поле	Опис
EditTextStyleAdditional editTextStyleAdditional = new EditTextStyleAdditional();	створюємо новий стиль
editTextStyleAdditional.setTextColor(Color.parseColor("#6A5ACD"));	колір тексту
editTextStyleAdditional.setErrorTextColor(Color.parseColor("#90EE90"));	колір помилки
editTextStyleAdditional.setHintTextColor(Color.parseColor("#C0C0C0"));	колір підказки
editTextStyleAdditional.setFocusedBorderColor(Color.parseColor("#7FFFD4"));	рамка в фокусі, тобто коли користувач щось вводить
editTextStyleAdditional.setUnfocusedBorderColor(Color.parseColor("#4682B4"));	рамка не фокусі, тобто коли користувач на іншому елементі
editTextStyleAdditional.setSizeFocusedBorderThickness(4);	товщина рамки поля вводу, якщо в фокусі поле вводу
editTextStyleAdditional.setSizeUnfocusedBorderThickness(2);	товщина рамки поля вводу, якщо в не фокусі поле вводу
editTextStyleAdditional.setSizeRoundedCornerShape(16);	закруглення рамки поля вводу
appStyle.setEditTextStyleAdditional(editTextStyleAdditional);	додаємо стиль до appStyle

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), можна двома способами:

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

5.1.1. Метод performTransaction

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

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

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

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

Об’єкт CardPaymentParams

Поле	Тип	Опис	Nullability
payeeId	String	Унікальний ідентифікатор компанії-отримувача в системі Portmone	Nonnull
billNumber	String	Унікальний номер платежу	Nullable
shopBillId	String	Ідентифікатор рахунку, що використовується для здійснення оплати за вже створеним рахунком. Якщо передається shopBillId, значення параметра preauthFlag, вказаного при створенні рахунку, має збігатися зі значенням у запиті на оплату. Параметр shopBillId необхідно розміщувати після billNumber (або після payeeId, якщо billNumber відсутній). Якщо shopBillId не використовується, залиште це поле порожнім ("") — у цьому випадку система працюватиме за стандартними налаштуваннями. Щоб коректно відображати користувачу номер замовлення, опис платежу та комісію, ці дані зі створеного shopBillId мають дублюватися і в параметрах запиту на оплату. Використання цього параметра є необов’язковим і потрібне лише тоді, коли оплата має виконуватися за попередньо створеним рахунком	Nullable
preAuth	boolean	Оплата з преавторизацією. Якщо не встановлено значення – false	Nullable
billCurrency	String	Валюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, 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
emailAddress	String	Електронна пошта	Nullable
privatPayEnabled	boolean	Оплата через систему LiqPay, з вибором картки з Інтернет-банкінгу Приват24. Параметр можна використовувати лише при виклику конструктора з Google Pay. Якщо оплата через через систему LiqPay не потрібна, цей параметр можна встановити як false	Nonnull
subscriptionInitPayment	String	Ознака ініціюючої оплати підписки. Значення "Y" – оплата оформлює підписку: проводиться з проходженням 3D Secure, після успішної оплати повертається Токен для списань за підпискою; "N" або значення не передано – звичайна оплата. Використовується лише для оплати карткою. Обов’язковий для оформлення підписки. Умови списань за підпискою див. у розділі «Проведення оплати за токеном без CVV2 (рекурентний платіж)» документації Payment Gateway (* параметр доступний з версії 3.0.18 SDK)	Nullable

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

Приклад:

final CardPaymentParams testParamsWithoutGooglePay = new PaymentParams(
    "1234",                 // payeeId
    "BILL-2025-0001",       // billNumber
    "2102095545",           // shopBillId
    false,                  // preAuth
    "UAH",                  // billCurrency
    "A1",                   // attribute1
    "A2",                   // attribute2
    "A3",                   // attribute3
    "A4",                   // attribute4
    "A5",                   // attribute5
    123.45,                 // billAmount
    "Test order 001",       // description
    "[email protected]",     // emailAddress
    "N"                     // subscriptionInitPayment
);

final CardPaymentParams testParamsWithGooglePay = new PaymentParams(
    "1234",                 // payeeId
    "BILL-2025-0001",       // billNumber
    "2102095545",           // shopBillId
    false,                  // preAuth
    "UAH",                  // billCurrency
    "A1",                   // attribute1
    "A2",                   // attribute2
    "A3",                   // attribute3
    "A4",                   // attribute4
    "A5",                   // attribute5
    123.45,                 // billAmount
    "Test order 001",       // description
    true,                   // onlyGooglePay
    false,                  // testEnvironment
    "[email protected]",     // emailAddress
    false                   // privatPayEnabled
);


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

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

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

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

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

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

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

Екран оплати карткою (приклад стиліз�ації)

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

Екран оплати карткою (приклад кастомної стилізації)

Мал. 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 (PreauthCardPreActivity), можна двома способами:

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

6.1.1. Метод performTransaction

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

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

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

Об’єкт SaveCardParams

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

Приклад:

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

PreauthCardActivity.performTransaction(
     this,
     113,
     testParams
);

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

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

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

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

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

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

6.1.2. Метод Activity Result APIs

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

PreauthCardContract;
ActivityResultCallback.

Параметри методу 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 (TokenActivity), можна двома способами:

за допомогою статичного методу performTransaction;
за допомогою 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
shopBillId	String	Ідентифікатор рахунку, що використовується для здійснення оплати за вже створеним рахунком. Якщо передається shopBillId, значення параметра preauthFlag, вказаного при створенні рахунку, має збігатися зі значенням у запиті на оплату. Параметр shopBillId необхідно розміщувати після billNumber (або після payeeId, якщо billNumber відсутній). Якщо shopBillId не використовується, залиште це поле порожнім ("") — у цьому випадку система працюватиме за стандартними налаштуваннями. Щоб коректно відображати користувачу номер замовлення, опис платежу та комісію, ці дані зі створеного shopBillId мають дублюватися і в параметрах запиту на оплату. Використання цього параметра є необов’язковим і потрібне лише тоді, коли оплата має виконуватися за попередньо створеним рахунком	Nullable
preAuth	boolean	Оплата з преавторизацією. Якщо не встановлено значення – false	Nullable
billCurrency	String	Валюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, 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	Опис платежу	Nonnull
onlyGooglePay	boolean	Для оплати виключно через Google Pay	Nullable
testEnvironment	boolean	Використання тестового середовища для Google Pay	Nullable
privatPayEnabled	boolean	Оплата через систему LiqPay, з вибором картки з Інтернет-банкінгу Приват24. Параметр можна використовувати лише при виклику конструктора з Google Pay. Якщо оплата через через систему LiqPay не потрібна, цей параметр можна встановити як false	Nonnull

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

Приклад:

final TokenPaymentParams testParamsWithoutGooglePay = new TokenPaymentParams(
    "1234",                 // payeeId
    "BILL-2025-1001",       // billNumber
    "2102095545",           // shopBillId
    false,                  // preAuth
    "UAH",                  // billCurrency
    "A1",                   // attribute1
    "A2",                   // attribute2
    "A3",                   // attribute3
    "A4",                   // attribute4
    "A5",                   // attribute5
    99.99,                  // billAmount
    "4444 33** **** 1111",  // cardMask
    "21312321321321321",    // token
    "Token pay no GP"       // description
);

final TokenPaymentParams testParamsWithGooglePay = new TokenPaymentParams(
    "1234",                 // payeeId
    "BILL-2025-1001",       // billNumber
    "2102095545",           // shopBillId
    false,                  // preAuth
    "UAH",                  // billCurrency
    "A1",                   // attribute1
    "A2",                   // attribute2
    "A3",                   // attribute3
    "A4",                   // attribute4
    "A5",                   // attribute5
    99.99,                  // billAmount
    "4444 33** **** 1111",  // cardMask
    "21312321321321321",    // token
    "Token pay GP",         // description
    true,                   // onlyGooglePay
    false,                  // testEnvironment
    false                   // privatPayEnabled
);


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

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

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

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

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

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

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

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

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

7.1.2. Метод Activity Result APIs

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

TokenPaymentContract;
ActivityResultCallback.

Параметри методу 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), можна двома способами:

за допомогою статичного методу performTransaction;
за допомогою 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
shopBillId	String	Ідентифікатор рахунку, що використовується для здійснення оплати за вже створеним рахунком. Параметр shopBillId необхідно розміщувати після billNumber (або після payeeId, якщо billNumber відсутній). Якщо shopBillId не використовується, залиште це поле порожнім ("") — у цьому випадку система працюватиме за стандартними налаштуваннями. Використання цього параметра є необов’язковим і потрібне лише тоді, коли оплата має виконуватися за попередньо створеним рахунком.	Nullable
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",                 // payeeId
    "2102095545",           // shopBillId
    "B2",                   // attribute2
    "B3",                   // attribute3
    "B4",                   // attribute4
    50.00,                  // billAmount
    "4444 33** **** 1111",  // cardMask
    "21312321321321321"     // token
);

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

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

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

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

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

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

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

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

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

9.1.2. Метод Activity Result APIs

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

TokenTransferContract;
ActivityResultCallback.

Параметри методу 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 для перевірки.

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

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

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

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

Приклад ві�дображення екрану оплати за допомогою 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);
    }
}

12. Масова оплата комунальних рахунків

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

12.1 Збереження картки

12.1.1 Отримання credentials

Необхідно зробити запит POST з параметрами логіну і паролю користувача, для отриманя credentials https://www.portmone.com.ua/r3/api/merchant-bills

Приклад запиту:

{
  "method":"getcred",
  "params": {
     "data": {
       "login": "Login,
       "password": "Password"
      }
  },
  "id":"1"
}

Приклад успішної відповіді:

{
  "result": {
"credentials": "32397c10e4ccc5841ae706ed4b16d0eb42adce4e6890466663c140a017f6869c2a52f5d6384447"
  },
  "id": "1"
}

Зверніть увагу! Необхідно зберегти credentials. При зміні паролю необхідно сформувати credentials знову.

12.1.2 Збереження картки для масової оплати комунальних рахунків

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

Відкрити екран збереження картки для створення токену масового платежу (створений на рівні SDK PreauthPayBillsPreActivity) можна двома способами:

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

Метод performTransaction

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

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

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

Об’єкт SaveCardBillsParams

Поле	Тип	Опис	Nullability
contractNumber	String	Логін користувача	Nullable
attribute1	String	`Credentials` значення отримали в пункті 12.1.1	Nonnull
lang	String	Можливі значення: ukrainian, english	Nullable

Приклад:

final SaveCardBillsParams saveCardBillsParams = new SaveCardBillsParams(
       "uk",
       "VERIFICATION",
       “Credentials”,
       “contractNumber”,
       "CREATE_TOKEN_BILL");

Метод Activity Result APIs

Аналогічно до методу Activity Result APIs (п. 6.1.2), тільки обєкт SaveCardBillsParams

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

У результаті ми отримаємо обєкт Bill, де нас цікавить властивість token

private ActivityResultLauncher<SaveCardBillsParams> resultLauncher =
       registerForActivityResult(
       new PreauthCardBillsContract(),
       result -> {
           result.handleResult(
                   (successResult) -> {
                       tvResult.setText("Payment result:\n" + successResult.getBill().toString());
                       saveCardBills(successResult.getBill());
                       return null;
                   },
                   (failureResult) -> {
                       tvResult.setText("Payment error:\n" + "Code" + failureResult.getCode() +
                               "\n" + failureResult.getMessage());
                       return null;
                   },
                   () -> {
                       tvResult.setText("Payment has been cancelled");
                       return null;
                   });
       }
);

Зверніть увагу! Для подальшого використання в оплаті необхідно зберегти такі параметри : token, credentials, contractNumber

12.2. Масова оплата комунальних рахунків за токеном

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

Для виклику екрану оплати за токеном необхідно викликати метод resultLauncher.launch(payBillsParams);

Приклад:

private ActivityResultLauncher<PayBillsParams> resultLauncher =
       registerForActivityResult(new MassPayContract(),
               result ->
                       result.handleResult((successResult) -> {
                                   tvResult.setText("Payment result, count payed bills:\n" + successResult.getBills().size());
                                   for (int i = 0; i < successResult.getBills().size(); i++) {
                                       tvResult.append("\nBillId = " + successResult.getBills().get(i).getBillId());
                                       tvResult.append("\nBillAmount = " + successResult.getBills().get(i).getBillAmount());
                                       tvResult.append("\nCommission = " + successResult.getBills().get(i).getCommission());
                                       tvResult.append("\nStatus = " + successResult.getBills().get(i).getStatus());
                                       tvResult.append("\nErrorCode = " + successResult.getBills().get(i).getErrorCode());
                                       tvResult.append("\nErrorMessage = " + successResult.getBills().get(i).getErrorMessage());
                                       tvResult.append("\n========================================");
                                   }
                               },
                               (failureResult) -> {
                                   tvResult.setText("Payment error:\n" + "Code" + failureResult.getCode() +
                                           "\n" + failureResult.getMessage());
                               },
                               () -> {
                                   tvResult.setText("Payment has been cancelled");
                               }));

У результаті повертаємо массив рахунків, статус кожного можна переглянути.

Об’єкт BillsPaymentParams

Поле	Тип	Опис	Nullability
contractNumber	String	Логін користувача	required
paymentBills	ArrayList`<MassPayBill>`	Масив рахунків на оплату. MassPayBill включає в себе 2 обовязкові параметри, це: id: String, (Приклад: “123456789”.), billAmount: Double, (Приклад: “1.00”.)	required
credentials	String	отримали в 12.1.1	required
googlePayEnabled	Boolean	Оплата Google Pay доступна в разі оплати тільки одного рахунку, якщо рахунків більше - встановлене значення буде за замовчуванням false. (дивись приклад)	optional
token	String	отримали в 12.1.2	required

13. Оплата BankPay

13.1. Ініціалізація оплати BankPay

Для виклику екрана оплати BankPay необхідно викликати CardPaymentActivity, як описано в пункті 5 «Оплата карткою», передавши коректно сконфігурований об'єкт CardPaymentParams.

Об’єкт CardPaymentParams

Поле	Тип	Опис	Nullability
payeeId	String	Унікальний ідентифікатор компанії-отримувача в системі Portmone	Nonnull
billNumber	String	Унікальний номер платежу	Nullable
shopBillId	String	Ідентифікатор рахунку, що використовується для здійснення оплати за вже створеним рахунком. Якщо передається shopBillId, значення параметра preauthFlag, вказаного при створенні рахунку, має збігатися зі значенням у запиті на оплату. Параметр shopBillId необхідно розміщувати після billNumber (або після payeeId, якщо billNumber відсутній). Якщо shopBillId не використовується, залиште це поле порожнім ("") — у цьому випадку система працюватиме за стандартними налаштуваннями. Щоб коректно відображати користувачу номер замовлення, опис платежу та комісію, ці дані зі створеного shopBillId мають дублюватися і в параметрах запиту на оплату. Використання цього параметра є необов’язковим і потрібне лише тоді, коли оплата має виконуватися за попередньо створеним рахунком	Nullable
preAuth	boolean	Оплата з преавторизацією. Якщо не встановлено значення – false	Nullable
billCurrency	String	Валюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, 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	Значення false	Nonnull
googlePayEnabled	boolean	Значення false	Nonnull
testEnvironment	boolean	Значення false	Nonnull
emailAddress	String	Електронна пошта	Nullable
privatPayEnabled	boolean	Значення true	Nonnull
onlyBankPay	boolean	Значення true	Nonnull
bankPayContractNumber	String	Значення “”	Nonnull

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

Приклад:

val testParams = CardPaymentParams(
    payeeId,
    "",
    "",
    false,
    Constant.BillCurrency.UAH,
    "",
    "",
    "",
    "", 
	"",
    31000.00,
    "test description",
    googlePayEnabled = true,
    onlyGooglePay = false,
    testEnvironment = false,
    emailAddress = "",
    privatPayEnabled = true,
    onlyBankPay = true,
    bankPayContractNumber = ""
)
launcher.launch(
    CardPaymentContractParams(
        testParams,
        showReceiptScreen = true,
        returnToDetailsAfterErrorEnabled = true
    )
)

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

Необхідно реалізувати інтерфейс PortmoneSDK.BankPayPaymentCallback, якщо потрібно обробляти такі події:

-успішна оплата;
-неуспішна оплата;
-на екрані успішної оплати користувач натиснув «Обрати інший платіжний метод»;
-на екрані успішної оплати користувач натиснув «На головний екран».

override fun bankPayPaymentSuccess(shopBillId: String, link: String) {
        // handle successful payment
    }

    override fun bankPayPaymentError(code: Long, message: String?) {
        // handle payment error
    }

    override fun bankPayPaymentToOther() {
        // payment succeeded, user selected "Other payment method"
    }

    override fun bankPayPaymentToMainScreen() {
        // payment succeeded, user returned to main screen
    }

Коди помилок

Код помилки	Опис
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].

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

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

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

Інтеграція​

settings.gradle (project level)​

build.gradle (project level)​

build.gradle (app level)​

Сканування картки (Google Payment Card Recognition API)​

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

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

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

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

App style​

Додаткова кастомізація екранів для зберігання картки та оплати карткою.​

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

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

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

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

5.1.1. Метод performTransaction​

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

Об’єкт CardPaymentParams​

5.1.2. Метод Activity Result APIs​

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

Об’єкт CardPaymentContractParams​

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

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

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

6.1.1. Метод performTransaction​

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

Об’єкт SaveCardParams​

6.1.2. Метод Activity Result APIs​

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

Об’єкт SaveCardParams​

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

Об’єкт Bill​

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

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

7.1.1. Метод performTransaction​

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

Об’єкт TokenPaymentParams​

7.1.2. Метод Activity Result APIs​

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

Об’єкт TokenPaymentContractParams​

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

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

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

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

9.1.1. Метод performTransaction​

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

Об’єкт TokenTransferParams​

9.1.2. Метод Activity Result APIs​

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

Об’єкт TokenTransferContractParams​

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

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

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

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

Об’єкт Bill​

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

12. Масова оплата комунальних рахунків​

12.1 Збереження картки​

12.1.1 Отримання credentials​

12.1.2 Збереження картки для масової оплати комунальних рахунків​

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

Об’єкт SaveCardBillsParams​

12.2. Масова оплата комунальних рахунків за токеном​

12.2.1 Ініціалізація оплати за токеном​

Об’єкт BillsPaymentParams​

13. Оплата BankPay​

13.1. Ініціалізація оплати BankPay​

Об’єкт CardPaymentParams​

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

Коди помилок​

Тестування​

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

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

Інтеграція

settings.gradle (project level)

build.gradle (project level)

build.gradle (app level)

Сканування картки (Google Payment Card Recognition API)

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

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

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

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

App style

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

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

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

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

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

5.1.1. Метод performTransaction

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

Об’єкт CardPaymentParams

5.1.2. Метод Activity Result APIs

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

Об’єкт CardPaymentContractParams

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

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

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

6.1.1. Метод performTransaction

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

Об’єкт SaveCardParams

6.1.2. Метод Activity Result APIs

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

Об’єкт SaveCardParams

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

Об’єкт Bill

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

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

7.1.1. Метод performTransaction

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

Об’єкт TokenPaymentParams

7.1.2. Метод Activity Result APIs

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

Об’єкт TokenPaymentContractParams

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

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

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

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

9.1.1. Метод performTransaction

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

Об’єкт TokenTransferParams

9.1.2. Метод Activity Result APIs

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

Об’єкт TokenTransferContractParams

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

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

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

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

Об’єкт Bill

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

12. Масова оплата комунальних рахунків

12.1 Збереження картки

12.1.1 Отримання credentials

12.1.2 Збереження картки для масової оплати комунальних рахунків

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

Об’єкт SaveCardBillsParams

12.2. Масова оплата комунальних рахунків за токеном

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

Об’єкт BillsPaymentParams

13. Оплата BankPay

13.1. Ініціалізація оплати BankPay

Об’єкт CardPaymentParams

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

Коди помилок

Тестування