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:2.2.0'){
exclude group: 'io.card'
}
}
В такому випадку із UI SDK буде прибрано функціонал сканування карток, що в свою чергу дасть виграш у зменшенні розміру додатку.
Якщо використовуєте proguard потрібно дадати наступний рядок: keep class com.portmone.ecomsdk.** { *; }
Сценарії використання
- Оплата карткою.
- Збереження картки.
- Оплата за токеном (токен картки може бути отриманий за сценарієм 1 або 2).
- Переказ коштів з картки на картку за токеном картки відправника.
- Оплата з підтвердженням відбитком пальця.
- Оплата з використанням 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), можна двома способами:
- за допомогою статичного методу 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 | 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, 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), можна двома способами:
- за допомогою статичного методу performTransaction;
- за допомогою Activity Result APIs.