Skip to main content

Portmone eCommerce Android SDK

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

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

build.gradle (app level)
dependencies {
implementation ('com.portmone.ecomsdk:ecomsdk:2.2.5'){
exclude group: 'io.card'
}
}

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

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

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

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

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

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

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

PortmoneSDK.setLanguage(languageСode);

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

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

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

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

PortmoneSDK.setAppStyle(...);

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

App style

ПолеТипОпис
backgroundintКолір заднього фону екранів
toolbarintКолір панелі інструментів на всіх екранах
iconSuccessintДозволяє змінити іконку успішної оплати (доступна з версії 1.2.1 SDK)
iconErrorintДозволяє змінити іконку неуспішної оплати (доступна з версії 1.2.1 SDK)
typeConstant$Type.*Цей параметр встановлюється за допомогою значень, які знаходяться у файлі Constant$Type. Можливі три варіанти:
1. Default – стандартний варіант;
2. Phone – відбувається заміна текста заголовка опису “Опис замовлення” на “Номер телефону”, а також до самого значення опису додається “+380” (доступна з версії 1.2.1 SDK)
3. Account – відбувається заміна текста заголовка опису “Опис замовлення” на “Номер особового рахунку” (доступна з версії 1.3.3 SDK)
buttonStyleButtonStyleМістить колір тексту кнопки та заднього фону в звичайному та натиснутому станах, шрифт для тексту кнопки, а також величину заокруглення кнопок
editTextStyleEditTextStyleВикористовується для полей вводу тексту. Дозволяє змінювати колір основного тексту, тексту підказки та помилки, а також відповідні шрифти
blockTitleTextStyleBlockTitleTextStyleВикористовується для заголовків блоків на екранах. Дозволяє вказувати колір фону, тексту та шрифт
titleTextStyleTitleTextStyleДозволяє вказувати колір та шрифт заголовків на екранах
descriptionTextStyleTextStyleДозволяє вказувати колір та шрифт основних текстів на екранах
additionalInfoTextStyleTextStyleДозволяє вказувати колір та шрифт додаткових текстів на екранах
fingerprintButtonTextStyleДозволяє вказувати колір та шрифт тексту кнопки оплати за допомогою відбитку пальця (доступна з версії 1.1.4 SDK)
paymentSuccessDownloadTextStyleДозволяє вказувати колір та шрифт тексту кнопки збереження квитанції на екрані успішної оплати (доступна з версії 1.2.1 SDK)
dialogInfoStyleDialogInfoStyleДозволяє вказувати колір та шрифт заголовку, тексту та тексту кнопки у діалогових вікнах
paymentDividerTextStyleКолір текстового розділювача поміж видами оплат (Google Pay та картка)

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

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

5.1.1. Метод performTransaction

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

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

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

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

Об’єкт PaymentParams

ПолеТипОписNullability
payeeIdStringУнікальний ідентифікатор компанії-отримувача в системі PortmoneNonnull
billNumberStringУнікальний номер платежуNullable
preAuthbooleanОплата з преавторизацією. Якщо не встановлено значення – falseNullable
billCurrencyStringВалюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, KZTNullable
attribute1StringАтрибут оплати 1Nullable
attribute2StringАтрибут оплати 2Nullable
attribute3StringАтрибут оплати 3Nullable
attribute4StringАтрибут оплати 4Nullable
attribute5StringАтрибут оплати 5. Використовується для передачі параметрів розщеплення платежу (детальний опис процедури наведений у розділі «Розщеплення платежу»)Nullable
billAmountdoubleСума платежуNonnull
descriptionStringОпис платежуNullable
onlyGooglePaybooleanДля оплат виключно через Google PayNullable
testEnvironmentbooleanВикористання тестового середовища для Google PayNullable
emailAddressStringЕлектронна пошта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б. Екран оплати карткою (приклад стилізації)

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

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

5.1.2. Метод Activity Result APIs

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

  • CardPaymentContract;
  • ActivityResultCallback.

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

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

ПараметрТипОпис
successHandlerPaymentResultHandler.SuccessCallback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandlerPaymentResultHandler.FailureCallback для опрацювання помилкового результату
cancelHandlerPaymentResultHandler.CancelCallback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

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

Об’єкт CardPaymentContractParams

ПараметрТипОписNullability
paymentParamsCardPaymentParamsНабір параметрів, необхідних для проведення оплатиNonnull
showReceiptScreenbooleanПараметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)Optional
returnToDetailsAfterErrorEnabledbooleanParameter 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), можна двома способами:

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

6.1.1. Метод performTransaction

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

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

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

Об’єкт SaveCardParams

ПолеТипОписNullability
payeeIdStringУнікальний ідентифікатор компанії-отримувача в системі PortmoneNonnull
billNumberStringУнікальний номер платежуNullable
descriptionStringОпис платежуNonnull
emailAddressStringЕлектронна пошта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.

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

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

ПараметрТипОпис
successHandlerPaymentResultHandler.SuccessCallback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandlerPaymentResultHandler.FailureCallback для опрацювання помилкового результату
cancelHandlerPaymentResultHandler.CancelCallback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

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

Об’єкт SaveCardParams

ПараметрТипОписNullability
paymentParamsSaveCardParamsНабір параметрів, необхідних для збереження карти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
billIdStringІдентифікатор здійсненої оплатиNonnull
cardMaskStringМаска картки, яка була використана для оплати, з першими шістьма та останніми чотирма цифрами номеру карткиNonnull
payDatelongЧас здійсненої оплати в мілісекундахNullable
payeeNameStringНазва компанії, на яку проводилась оплатаNullable
tokenStringТокен проведеної оплатиNullable

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

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

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

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

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

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

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

7.1.1. Метод performTransaction

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

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

ПараметрТипОписПриклад
activity/fragmentActivity/FragmentОб’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCodeintУнікальний код для ідентифікації результату проведеної оплати123
paramsTokenPaymentParamsНабір параметрів, необхідних для проведення оплати
showReceiptScreenbooleanПараметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true)
(* параметр доступний з версії 1.3.2 SDK)
returnToDetailsAfterErrorEnabledbooleanПараметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false)
(* параметр доступний з версії 1.3.4 SDK)

Об’єкт TokenPaymentParams

ПолеТипОписNullability
payeeIdStringУнікальний ідентифікатор компанії-отримувача в системі PortmoneNonnull
billNumberStringУнікальний номер платежуNullable
preAuthbooleanОплата з преавторизацією. Якщо не встановлено значення – falseNullable
billCurrencyStringВалюта, в якій здійснюватиметься платіж. Приймаються значення тільки з набору констант: Constant$BillCurrency. Можливі значення: UAH (стандартна), USD, EUR, GBP, KZTNullable
attribute1StringАтрибут оплати 1Nullable
attribute2StringАтрибут оплати 2Nullable
attribute3StringАтрибут оплати 3Nullable
attribute4StringАтрибут оплати 4Nullable
attribute5StringАтрибут оплати 5. Використовується для передачі параметрів розщеплення платежу (детальний опис процедури наведений у розділі «Розщеплення платежу»)Nullable
billAmountdoubleСума платежуNonnull
cardMaskStringМаска збереженої карткиNonnull
tokenStringТокен збереженої карткиNonnull
descriptionStringОпис платежуNonnull
onlyGooglePaybooleanДля оплати виключно через Google PayNullable
testEnvironmentbooleanВикористання тестового середовища для Google PayNullable

Примітка: поля 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
);

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

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

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

ПараметрТипОпис
successHandlerPaymentResultHandler.SuccessCallback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandlerPaymentResultHandler.FailureCallback для опрацювання помилкового результату
cancelHandlerPaymentResultHandler.CancelCallback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

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

Об’єкт TokenPaymentContractParams

ПараметрТипОписNullability
paymentParamsTokenPaymentParamsНабір параметрів, необхідних для проведення оплатиNonnull
showReceiptScreenbooleanПараметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)Optional
returnToDetailsAfterErrorEnabledbooleanПараметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (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/fragmentActivity/FragmentОб’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCodeintУнікальний код для ідентифікації результату проведеного переказу123
paramsTokenTransferParamsНабір параметрів, необхідних для проведення переказу
showReceiptScreenbooleanПараметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true)
(* параметр доступний з версії 1.3.2 SDK)
returnToDetailsAfterErrorEnabledbooleanПараметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (default false)
(* параметр доступний з версії 1.3.4 SDK)

Об’єкт TokenTransferParams

ПолеТипОписNullability
payeeIdStringУнікальний ідентифікатор компанії-отримувача в системі PortmoneNonnull
attribute2StringАтрибут оплати 2Nullable
attribute3StringАтрибут оплати 3Nullable
attribute4StringАтрибут оплати 4Nullable
billAmountdoubleСума платежу. Якщо параметр не задано, то його можна задати вручну на екрані оплатиNullable
cardMaskStringМаска збереженої карткиNonnull
tokenStringТокен збереженої картки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

ПараметрТипОпис
successHandlerPaymentResultHandler.SuccessCallback для опрацювання успішного результату, в якому можна отримати Bill про оплату та спосіб оплати (за допомогою Google Pay чи без)
failureHandlerPaymentResultHandler.FailureCallback для опрацювання помилкового результату
cancelHandlerPaymentResultHandler.CancelCallback для опрацювання скасування оплати (наприклад, при закритті користувачем екрану SDK)

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

Об’єкт TokenTransferContractParams

ПараметрТипОписNullability
paymentParamsCardPaymentParamsНабір параметрів, необхідних для проведення оплатиNonnull
showReceiptScreenbooleanПараметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.3.2 SDK)Optional
returnToDetailsAfterErrorEnabledbooleanПараметр, за допомогою якого можна заборонити повернення до введення реквізитів після виникнення помилки (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
onlyGooglePaybooleanДля оплат виключно через Google PayNullable
testEnvironmentbooleanВикористання тестового середовища для Google PayNullable

Важливо! Перед релізом додатку необхідно отримати погодження від команди 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
billIdStringІдентифікатор здійсненої оплатиNonnull
statusStringСтатус проведеної оплати. Можливі значення “PAYED” та “PREAUTH”, в залежності від потрібного типу оплати, вибраного під час ініціалізаціїNonnull
billAmountdoubleСума проведеної оплатиNonnull
commissionAmountdoubleКомісія проведеної оплатиNullable
cardMaskStringМаска картки, яка була використана для оплати, з першими шістьма та останніми чотирма цифрами номеру карткиNonnull
recieptUrlStringПосилання на pdf з квитанцієюNullable
contractNumberStringНомер особового рахункуNullable
payDatelongЧас здійсненої оплати в мілісекундахNullable
payeeNameStringНазва компанії, на яку проводилась оплатаNullable
tokenStringТокен проведеної оплати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/fragmentActivity/FragmentОб’єкт Activity/Fragment, необхідний для запуску екрану оплати, а також для отримання результату оплати
requestCodeintУнікальний код для ідентифікації результату проведеної оплати
paramsSaveCardParamsНабір параметрів, необхідних для збереження картки

Об’єкт SaveCardBillsParams

ПолеТипОписNullability
contractNumberStringЛогін користувачаNullable
attribute1StringCredentials значення отримали в пункті 12.1.1Nonnull
langStringМожливі значення: ukrainian, englishNullable

Приклад:

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

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

7.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
contractNumberStringЛогін користувачаrequired
paymentBillsArrayList<MassPayBill>Масив рахунків на оплату.Об’єкт MassPayBill включає в себе обовязкові 2 параметри, це:
id: String, (Приклад: “123456789”.)
billAmount: Double, (Приклад: “1.00”.)required
credentialsStringотримали в 12.1.1required
googlePayEnabledBooleanОплата Google Pay доступна в разі оплати тільки одного рахунку, якщо рахунків більше - встановлене значення буде за замовчуванням false. (дивись приклад)optional
tokenStringотримали в 12.1.2required

Коди помилок

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

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