Portmone eCommerce iOS SDK
Терміни та визначення
Термін | Визначе ння |
---|---|
Мерчант, Інтернет-магазин або Партнер | Організація, що уклала договір з Portmone.com про надання послуг з приймання платежів |
Покупець, Клієнт | Відвідувач Інтернет-магазину Мерчанта з метою ознайомлення з асортиментом товарів (послуг) та здійснення покупки |
Картка, Платіжна картка | Платіжні картки міжнародних платіжних систем Visa, Mastercard та Національної платіжної системи ПРОСТІР |
Токен | Цифровий ідентифікатор картки, що генерується при першій операції і далі використовується для швидкої оплати |
Авторизація | Процедура отримання підтвердження від банка-емітента на проведення операції оплати карткою |
Біометрична авторизація | Процес підтвердження платежу за допомогою технології ідентифікації біометричних даних (відбитків пальців, форми обличчя) |
Банк-емітент банківських карток | Банк, що є учасником платіжної системи та здійснює випуск (емісію) та обслуговування банківських карток |
3-D Secure | 3-D Secure - це протокол, який використовувався для забезпечення додаткового рівня безпеки онлайн-платежів з використанням банківських карток |
Загальний опис
Portmone SDK e-com підтримує версію iOS 8.0 та пізніші версії.
Може бути інтегроване в проект двома способами:
- копіювати PortmoneSDKEcom.framework вручну в проект:
Target → Build Phases → Embed Frameworks додати цей файл і виставити Destination → Frameworks
- використати CocoaPods:
pod 'PortmoneSDKEcom'
Сценарії використання
- Оплата карткою.
- Отримання токену (збереження картки).
- Оплата за токеном (токен картки може бути отриманий за сценарієм 1 або 2).
- Переказ з токену на номер картки.
- Оплата через Apple Pay.
- Оплата за допомогою Touch/Face ID.
Опис програмного інтерфейсу
1. Початок роботи з SDK
Для використання методів SDK перед початком роботи необхідно ініціалізувати Payment Presenter, який приймає набір параметрів:
/// Initializer
public init(delegate: PaymentPresenterDelegate,
styleSource: StyleSource? = nil,
language: PortmoneSDKEcom.PaymentPresenter.Language? = nil,
biometricAuth: Bool = false),
customUid: String? = nil)
Параметри
Поле | Тип | Опис | Nullability |
---|---|---|---|
delegate | PaymentPresenterDelegate | Протокол для зворотнього зв’язку SDK. Надає інформацію про стан платежу | required |
styleSource | StyleSource | Протокол для кастомізації елементів на екранах | optional |
language | Language | Енам для встановлення мови інтерфейсу SDK. Можливі значення: ukrainian, english. Якщо параметр не передано, буде використовуватись мова пристрою клієнта | optional |
biometricAuth | Bool | Параметр для активації біометричної авторизації. Значення без задання: false | optional |
customUid | String | Ідентифікатор ендпоінту, на який будуть надсилатись запити. Необхідність заповнення погоджується з менеджером Portmone.com | optional |
Зверніть увагу - для того, щоб увімкнути можливість біометричної авторизації, необхідно надіслати відповідного листа з зареєстрованої адреси електронної пошти менеджерам Portmone.com по співпраці на адресу [email protected].
Протокол PaymentPresenterDelegate
/// Method triggered as result of payment process.
///
/// - Parameter bill: Bill
/// - Parameter error: Error
func didFinishPayment(bill: PortmoneSDKEcom.Bill?, error: Error?)
/// Optional method.
/// Method triggered when PortmoneSDK had already dismissed.
func dismissedSDK()
Методи PayeePaymentDelegate
Метод | Параметри | Опис |
---|---|---|
didFinishPayment | PortmoneSDKEcom.Bill? Error? | Викликається після завершення оплати. У разі успішного проведення присутній об’єкт Bill, при виникненні помилки може бути присутня системна помилка або об’єкт протоколу Error |
dismissedSDK | Викликається після закриття користувачем вікна з оплатою |
Протокол StyleSource
/// Title label font (All screens)
func titleFont() -> UIFont
/// Title label color (All screens)
func titleColor() -> UIColor
/// Section header label font (Payment, commission screens)
func headersFont() -> UIFont
/// Section header label color (Payment, commission screens)
func headersColor() -> UIColor
/// Section header view background color (Payment, commission screens)
func headersBackgroundColor() -> UIColor
/// All textFields placeholder font
func placeholdersFont() -> UIFont
/// All textFields placeholder color
func placeholdersColor() -> UIColor
/// All textFields text font
func textsFont() -> UIFont
/// All textFields text color
func textsColor() -> UIColor
/// All error strings text font
func errorsFont() -> UIFont
/// All error strings text color
func errorsColor() -> UIColor
/// All background color (Table, cells, navigation bar)
func backgroundColor() -> UIColor
/// Message label font (Result, 2d verification screens)
func resultMessageFont() -> UIFont
/// Message label color (Result, 2d verification screens)
func resultMessageColor() -> UIColor
/// Save receipt title color (Result screen)
func resultSaveReceiptColor() -> UIColor
/// Informative label on button (Save card screen)
func infoTextsFont() -> UIFont
func infoTextsColor() -> UIColor
/// Buttons back and next title font
func buttonTitleFont() -> UIFont
/// Button bottom title color
func buttonTitleColor() -> UIColor
/// Buttons back and next tint color
func buttonColor() -> UIColor
/// Button corner radius
func buttonCornerRadius() -> CGFloat
/// Biometric button title color
func biometricButtonColor() -> UIColor
/// Image for success result
func successImage() -> UIImage?
/// Image for failure result
func failureImage() -> UIImage?
Метод | Повертає параметри | Опис |
---|---|---|
titleFont | UIFont | Відбувається зміна шрифту заголовків на всіх екранах. Розмір залишається сталим |
titleColor | UIColor | Відбувається зміна кольору заголовків на всіх екр анах |
headersFont | UIFont | Відбувається зміна шрифту всіх заголовків розділів. Розмір залишається сталим |
headersColor | UIColor | Відбувається зміна кольору всіх заголовків розділів |
headersBackgroundColor | UIColor | Відбувається зміна фонового кольору всіх заголовків розділів |
placeholdersFont | UIFont | Відбувається зміна шрифту заповнювачів на всіх екранах. Розмір залишається сталим |
placeholdersColor | UIColor | Відбувається зміна кольору заповнювачів на всіх екранах |
textsFont | UIFont | Відбувається зміна шрифту основних текстів у полях введення на всіх екранах. Розмір залишається сталим |
textsColor | UIColor | Відбувається зміна кольору основних текстів у полях введення на всіх екранах |
errorsFont | UIFont | Відбувається зміна шрифту помилок на всіх екранах. Розмір залишається сталим |
errorsColor | UIColor | Відбувається зміна кольору помилок на всіх екранах. Розмір залишається сталим |
backgroundColor | UIColor | Відбувається зміна фонового кольору на всіх екранах |
resultMessageFont | UIFont | Відбувається зміна шрифту інформаційного повідомлення на екранах 2д перевірки та результату оплати. Розмір шрифту залишається сталим |
resultMessageColor | UIColor | Відбувається зміна кольору інформаційного повідомлення на екранах 2д перевірки та результату оплати |
resultSaveReceiptColor | UIColor | Відбувається зміна кольору назви кнопки збереження квитанції на екрані результату оплати |
infoTextsFont | UIFont | Відбувається зміна шрифту інформаційного тексту на екрані збереження картки. Розмір шрифту залишається сталим |
infoTextsColor | UIColor | Відбувається зміна кольору інформаційного тексту на екрані збереження картки |
buttonTitleFont | UIFont | Відбувається зміна шрифту назв кнопок на всіх екранах. Розмір шрифту залишається сталим |
buttonTitleColor | UIColor | Відбувається зміна кольору назв кнопок на всіх екранах |
buttonColor | UIColor | Відбувається зміна фонового кольору або кольору назв кнопок на всіх екранах |
buttonCornerRadius | CGFloat | Відбувається зміна радісу заокруглення кнопок на всіх екранах |
biometricButtonColor | UIColor | Відбувається зміна кольору назви біометричної кнопки на екрані оплати за токеном |
successImage | UIImage? | Відбувається зміна іконки успішної оплати |
failureImage | UIImage? | Відбувається зміна іконки неуспішної оплати |
Приклад:
private var presenter: PaymentPresenter?
override func viewDidLoad() {
super.viewDidLoad()
presenter = PaymentPresenter(delegate: self,
styleSource: self,
language: .ukrainian,
biometricAuth: true),
customUid: “YOUR_CUSTOM_UID_FROM_PORTMONE”)
}
2. Оплата карткою
2.1. Ініціалізація оплати карткою
Для виклику екрану оплати карткою необхідно викликати метод presentPaymentByCard, передавши необхідні параметри.
PaymentPresenter
// Method to present payment by card screen
public func presentPaymentByCard(on controller: UIViewController,
params: PortmoneSDKEcom.PaymentParams,
showReceiptScreen: Bool)
// Method for changing SDK redirection point for unsuccessful payment results.
// If you set true - SDK will be dismissed, otherwise, SDK will return the user
// to previous page. The default value is false
public func setReturnToDetails(disabled: Bool)
Параметри методу presentPaymentByCard
Параметр | Тип | Опис | Nullability |
---|---|---|---|
controller | UIViewController | Контролер, поверх якого показується екран оплати карткою | required |
params | PaymentParams | Параметри, необхідні для проведення платежу | required |
showReceiptScreen | Bool | Параметр, за допомогою якого можна вимкнути відображення екрану із збереженням квитанції після успішної оплати (default true) (* параметр доступний з версії 1.4.0 SDK) | optional |
Об’єкт PaymentParams
Поле | Тип | Опис | Nullability |
---|---|---|---|
description | String | Опис призначення платежу | optional |
attribute1 | String | Атрибут оплати 1 | optional |
attribute2 | String | Атрибут оплати 2 | optional |
attribute3 | String | Атрибут оплати 3 | optional |
attribute4 | String | Атрибут оплати 4 | optional |
attribute5 | String | Атрибут оплати 5. Використовується для передачі параметрів розщеплення платежу (детальний опис процедури наведений у розділі «Розщеплення платежу») | optional |
billNumber | String | Номер рахунку, що сплачується. До 120 символів, повинен бути унікальним в рамках одного замовлення. Якщо замовлення з цим номером вже було оплачено, система Portmone.com відхилить транзакцію | optional |
preauthFlag | Bool | Режим преавторизації. Кошти не списуються з рахунку, а лише блокуються. Значення без задання: false | optional |
billCurrency | Currency | Валюта проведення платежу. Можливі значення: UAH (стандартна), USD, EUR, GBP, BYN, KZT | optional |
billAmount | Double | Сума замовлення. Приклад: “1.00” | required |
billAmountWcvv | Double | Максимальна сума замовлення, яку можна оплатити без введення CVV. Використовується при оплаті за токеном. Приклад: “1.00” | required |
payeeId | String | Ідентифікатор одержувача платежу | required |
type | PaymentType | Тип платежу. Може приймати одне з трьох значень: 1) .payment – стандартний варіант; 2) .mobilePayment – відбувається зміна текста заголовка опису на "Номер телефону", а до значення опису додається "+380"; 3) .account – відбувається зміна текста заголовка опису на “Номер особового рахунку” | optional |
merchantIdentifier | String | Ідентифікатор, який ви реєструєте в Apple, який однозначно ідентифікує ваш бізнес як мерчанта, здатного здійснювати платежі (MerchantID) | optional |
paymentFlowType | PaymentFlowType | Атрибут, який відповідає за можливі сценарії оплати: карткою, карткою або Apple Pay, або тільки Apple Pay. Можливі значення: .byCard (значення без задання), .byCardAndApplePay, .byApplePay | optional |
Приклад:
@IBAction private func payButtonClicked(_ sender: UIButton) {
var billNumb = ""
if billNumber.text?.isEmpty ?? true {
billNumb = "SD\(Int(Date().timeIntervalSince1970))"
} else {
billNumb = billNumber.text ?? ""
}
// Параметр withoutCVV використовується при оплаті за токеном
let flowType = PaymentFlowType(payWithCard: payWithCardSwitch.isOn,
payWithApplePay: payWithAPaySwitch.isOn,
withoutCVV: false)
let paymentParams = PaymentParams(description: contractNumber.text ?? "",
attribute1: attribute1.text ?? "",
attribute2: attribute2.text ?? "",
attribute3: attribute3.text ?? "",
attribute4: attribute4.text ?? "",
attribute5: attribute5.text ?? "",
billNumber: billNumb,
preauthFlag: preauthFlag.isOn,
billCurrency: .uah,
billAmount: Double(billAmount.text ?? "") ?? 0,
details: billDetails.text ?? "",
payeeId: payeeId.text ?? "",
merchantIdentifier: merchantIdTextField.text ?? "",
paymentFlowType: flowType)
// Виклик функції зі значенням true поверне користувача в додаток,
// повністю закривши SDK у випадку неуспішної оплати
presenter?.setReturnToDetails(disabled: true)
presenter?.presentPaymentByCard(on: self, params: initParams)
}