Masterpass iOS SDK · Документація

iOS інтеграція

Portmone SDK підтримує версію iOS 8.0 та пізніші версії.

Можливості, які надає Portmone SDK

Гаманець Masterpass:

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

Оплата:

поповнення мобільного за допомогою карток Masterpass;
оплата послуг за особовим рахунком за допомогою карток Masterpass.

Перед початком роботи

Реєстрація у Masterpass™

Для початку роботи з Masterpass™ необхідно пройти процес merchant-реєстрації на developers.mastercard.com. Для цього:

Перейдіть на https://developer.mastercard.com/account/sign-up
Заповніть анкетні дані та пройдіть процедуру підтвердження e-mail адреси
Створіть проект на сторінці https://developer.mastercard.com/dashboard → Create new project

Реєстрація у Portmone.com

Після отримання ключів від Masterpass™, передайте Portmone.com наступну інформацію:

Дані ключів з вашого особистого кабінету на https://developer.mastercard.com/masterpass/merchant/#/keyManagement2, а саме:
- Public key (Натисніть “Actions” → “Download *.pem”)
- Keystore password
- Key alias
Masterpass™ Checkout ID (скопіювати зі сторінки https://developer.mastercard.com/masterpass/merchant/#/checkoutCredentials у вашому особистому кабінеті)

Передати інформацію необхідно листом на [email protected] з темою “Partner [Назва вашої компанії] Onboarding”. Будь ласка, перевірте що в вас є постійний доступ до поштової скриньки, з якої ви надсилатимете цей лист, та скринька зареєстрована у довіреному домені вашої компанії. Листи з публічних безкоштовних доменів (gmail.com, yahoo.com, ukr.net тощо) буде автоматично відфільтровано. Після реєстрації даних вашого Masterpass™ Merchant у системі Portmone.com, з вами зв’яжуться для допомоги у подальших кроках інтеграції та тестування і передадуть наступну інформацію:

Portmone.com Merchant Id
Portmone.com Merchant Login
Поточну версію SDK для платформ iOS та/або Android разом із зразками додатків, що використовують SDK

1. Початок роботи з SDK

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

PortmoneSDK(merchantKey, clientId)

Параметри

Поле	Тип	Опис	Nullability
clientId	String	Унікальне ід клієнта в системі мастерпас	required
merchantKey	String	Унікальний ключ	required

2. Авторизація (AuthorizationService)

Для використання можливостей SDK потрібно авторизуватися в системі. Для авторизації використовується AuthorizationService, який публічно доступний та його метод authorize. Авторизація для одного користувача зберігається протягом життя додатку після виклику методу. Для зміни користувача потрібно викликати цей метод знову з іншими параметрами.

Під час виклику методу відбувається перевірка статусу гаманця за вказаним номером телефону, в разі необхідності автоматично відбувається лінкування клієнта до системи Masterpass. В такому випадку необхідна верифікація карти за допомогою OTP коду і з’явиться помилка 2113.

Авторизація

AuthorizationService

public func authorize(phone: String,
                      userId: String,
                      completion: @escaping OperationCompletion)

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

Параметр	Тип	Опис	Приклад
phoneNumber	String	Номер телефону користувача. Використовується як ідентифікатор в гаманці Masterpass.	“380666789555”
userId	String	Ід користувача в Portmone. Потрібен для ідентифікації в системі Portmone.	“3715100”
completion	OperationCompletion	Асинхронний колбек з результатом авторизації.

Отримання результату авторизації:

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

Параметри OperationCompletion

Параметри	Опис
Bool	Результат авторизації: true - успішний, false- невдалий.
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт Error. При перевірці статусу гаманця можливе виникнення помилки 2113, при якій необхідна OTP верифікація картки.

Приклад:

let service = AuthorizationService()
service.authorize(phone: "380666789555",
                  userId:"3714123") { [weak self] isSuccess, error in
            if error != nil {
                let code = (error as NSError?)?.code
                switch code {
                case 2113?:
                    self?.performSegue(withIdentifier: self?.confirmCardSegue ?? "", 
sender: self)

                default:
                    self?.presentAlert(title: "Error \(code ?? 0)",
                                       message: error?.localizedDescription)
                }
            } else {
                self?.presentAlert(title: "Success",
                                   message: "Authorization success.") { _ in
                    self?.performSegue(withIdentifier: "Functionality", sender: nil)
                }
            }
        }

3. Гаманець Masterpass (CardService)

Для роботи з гаманцем використовується CardService. Дає можливість додавати та видаляти картки, а також отримувати список карток в існуючому гаманці.

CardService

public func getMasterpassCards(completion: @escaping MasterpassCardsCompletion)

public func addMasterpassCard(card: MfsCard,
                              cardNumber: MfsTextField,
                              cvv: MfsTextField,
                              completion: @escaping OperationCompletion)

public func deleteMasterpassCard(cardName: String,
                                 completion: @escaping OperationCompletion)

3.1 Додавання картки (addMasterpassCard)

Метод додає картку в існуючий гаманець Masterpass по номеру телефону вказаному при авторизації або створює новий гаманець, якщо за даним номером існуючого не було знайдено.

Додавання картки

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

Параметр	Тип	Опис	Приклад
card	MfsCard	Назва карти, рік та місяць терміну дії картки повинні бути заповнені у об’єкті *MfsCard*. Назва карти повинна бути URL encoded.	Див. нижче
cardNumber	MfsTextField	Номер картки заповнений у об’єкті *MfsTextField*.	Див. нижче
cvv	MfsTextField	CVV код заповнений у об’єкті *MfsTextField*.	Див. нижче
completion	OperationCompletion	Асинхронний колбек з додавання карти.

Приклад параметру card:

let card = MfsCard()
card.cardName = "СardName"
card.expireMonth = "03”
card.expireYear = "20"

Приклад параметру cardNumber:

cardNumber.setType(1)
cardNumber.maxLength = 20
cardNumber.placeholder = "Card No"
cardNumber.keyboardType = .numberPad
cardNumber.clear()

Приклад параметру cvv:

cvv.setType(3)
cvv.maxLength = 3
cvv.placeholder = "cvv"
cvv.keyboardType = .numberPad
cvv.clear()

Отримання результату додавання карти:

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

Параметри OperationCompletion

Параметри

Опис

Bool

Результат додавання карти: true - успішний, false - невдалий.

Error?

Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.
При додаванні картки можливе виникнення помилок 2113, 2114, при яких необхідна OTP верифікація картки та номеру телефону.

Приклад:

final class AddCardViewController: BaseViewController {

    private let confirmPhoneSegue = "ConfirmPhone"
    private let confirmCardSegue = "ConfirmCard"
    private let cardService = CardsService()

    @IBOutlet private weak var cardName: UITextField!
    @IBOutlet private weak var cardNumber: MfsTextField!
    @IBOutlet private weak var expireMonth: UITextField!
    @IBOutlet private weak var expireYear: UITextField!
    @IBOutlet private weak var cvv: MfsTextField!

    override func viewDidLoad() {
        super.viewDidLoad()

        cardNumber.setType(1)
        cardNumber.maxLength = 20
        cardNumber.placeholder = "Card No"
        cardNumber.keyboardType = .numberPad
        cardNumber.clear()

        cvv.setType(3)
        cvv.maxLength = 3
        cvv.placeholder = "cvv"
        cvv.keyboardType = .numberPad
        cvv.clear()
    }

    @IBAction private func addCardButtonClicked(_ sender: UIButton) {
        let card = MfsCard()
        card.cardName = cardName.text 
        card.expireMonth = expireMonth.text
        card.expireYear = expireYear.text

        UIApplication.shared.isNetworkActivityIndicatorVisible = true
        cardService.addMasterpassCard(card: card,
                                      cardNumber: cardNumber,
                                      cvv: cvv) { [weak self] isSuccess, error in
            UIApplication.shared.isNetworkActivityIndicatorVisible = false
            if error != nil {
                let code = (error as NSError?)?.code
                switch code {
                case 2113?:
                    self?.performSegue(withIdentifier: self?.confirmCardSegue ?? "",
sender: self)

                case 2114?:
                    self?.performSegue(withIdentifier: self?.confirmPhoneSegue ?? "",
sender: self)

                default:
                    self?.presentAlert(title: "Error \(code ?? 0)",
                                       message: error?.localizedDescription)
                }
            } else {
                self?.presentAlert(title: "Success",
                                   message: "Add card success.") { _ in
                    self?.navigationController?.popViewController(animated: true)
                }
            }
        }
    }

    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
        if (segue.identifier == confirmPhoneSegue) {
            if let navController = segue.destination as? UINavigationController,
                let controller = navController.viewControllers.first as?
ConfirmCodeViewController {
                controller.delegate = self
                controller.type = .phone
            }
        }

        if (segue.identifier == confirmCardSegue) {
            if let navController = segue.destination as? UINavigationController,
                let controller = navController.viewControllers.first as?
ConfirmCodeViewController {
                controller.delegate = self
                controller.type = .card
            }
        }
    }
}

3.2 Отримання списку карток (getMasterpassCards)

Метод дозволяє отримати список існуючих карток для гаманця за номером телефону вказаному при авторизації.

Отримання списку карток

MasterpassCardsCompletion

public typealias MasterpassCardsCompletion = ([MasterpassCard]?, Error?) -> Void

Параметри MasterpassCardsCompletion

Параметри	Опис
[MasterpassCard]?	Викликається після успішного отримання карток. При успішному запиті метод повертає масив об’єктів *MasterpassCard*.
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

Об‘єкт MasterpassCard

Поле	Тип	Опис	Nullability
cardBin	String	Замаскований номер картки у форматі 444433********11.	required
name	String	Унікальна назва картки в гаманці Masterpass.	required

Приклад:

let cardService = CardsService()
cardService.getMasterpassCards { cards, error in
            if cards != nil {
                self.cards = cards
                self.tableView.reloadData()
            } else {
                let code = (error as NSError?)?.code
                self.presentAlert(title: "Error \(code ?? 0)",
                                  message: error?.localizedDescription)
            }
        }

3.3 Видалення картки (deleteMasterpassCard)

Метод видаляє картку з гаманця Masterpass.

Видалення картки

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

Параметр	Тип	Опис	Приклад
cardName	String	Назва картки в системі Masterpass. Отримується з властивості `name` об’єкта *MasterpassCard*	“MyCard”
completion	OperationCompletion	Асинхронний колбек з результатом видалення

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

Параметри OperationCompletion

Параметри	Опис
Bool	Результат додавання карти: true - успішний, false - невдалий.
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

Приклад:

let cardService = CardsService()
cardService.deleteMasterpassCard(cardName: "SomeCardName") { isSuccess, error in
                if isSuccess {
                    self.presentAlert(title: "Success",
                                      message: cardName + " card deleted.") { _ in
                        self.cards?.remove(at: indexPath.row)
                        self.tableView.reloadData()
                    }
                } else {
                    let code = (error as NSError?)?.code
                    self.presentAlert(title: "Error \(code ?? 0)",
                                      message: error?.localizedDescription)
                }
            }

4. OTP верифікація (validateCode)

Метод дозволяє проводити OTP валідацію номера телефону та банківської карти. Викликається при отриманні помилок з кодом 2113 або 2114. Може бути викликаний за допомогою AuthorizationService та CardsService. Після успішної перевірки може виникнути потреба в додатковій верифікації, тому результатом може бути помилка про необхідність верифікації з повторним викликом методу.

public func validateCode(code: MfsTextField, completion: @escaping OperationCompletion)

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

Параметр	Тип	Опис
code	MfsTextField	Об’єкт *MfsTextField* з заповненим кодом для валідації.
completion	OperationCompletion	Асинхронний колбек з результатом перевірки.

Приклад параметру code:

confirmCode.setType(2)
confirmCode.maxLength = 6
confirmCode.placeholder = "PIN"
confirmCode.keyboardType = .numberPad
confirmCode.clear()

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

Параметри OperationCompletion

Параметри	Опис
Bool	Результат валідації: true - успішний, false - невдалий.
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error. Можливі помилки 2113 і 2114, при який необхідна OTP валідація.

5. Отримання компаній (PayeeService)

Сервіс дозволяє отримати компанії, на які можна здійснювати оплату за допомогою SDK.

PayeeService

public func getPayees(completion: @escaping PayeesCompletion)

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

Параметр	Тип	Опис	Приклад
completion	PayeesCompletion	Асинхронний колбек з результатом отримання компаній.

PayeesCompletion

public typealias PayeesCompletion = ([Payee]?, Error?) -> Void

Параметри MasterpassCardsCompletion

Параметри	Опис
[Payee]?	При успішному запиті метод повертає масив об’єктів *Payee*.
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

Об’єкт Payee

Поле	Тип	Опис	Nullability
payeeId	String	Унікальне ід компанії	required
name	String	Назва компанії.	required
contractNumberTitle	PayeeLocalizedTitle	Назва номеру рахунку. Містить переклади на 3 мовах за ключами: “uk ” - українська, “en” = англійська, “ru” = російська	required
contractNumberType	String	Тип даних для номеру рахунку. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy".	required
contractNumberSize	String	Максимальний розмір поля.	optional
attribute1Title	PayeeLocalizedTitle	Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” = українська , “en” = англійська, “ru” = російська	optional
attribute1Type	String	Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy".	optional
attribute1Size	String	Максимальний розмір поля.	optional
attribute1ForInfo	boolean	При значенні true означає, що поле не має бути показане	optional
attribute2Title	PayeeLocalizedTitle	Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” = українська , “en” = англійська, “ru” = російська	optional
attribute2Type	String	Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy".	optional
attribute2Size	String	Максимальний розмір поля.	optional
attribute2ForInfo	boolean	При значенні true означає, що поле не має бути показане	optional
attribute3Title	PayeeLocalizedTitle	Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” = українська , “en” = англійська, “ru” = російська	optional
attribute3Type	String	Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy".	optional
attribute3Size	String	Максимальний розмір поля.	optional
attribute3ForInfo	boolean	При значенні true означає, що поле не має бути показане	optional
attribute4Title	PayeeLocalizedTitle	Назва атрибуту. Містить переклади на 3 мовах за ключами: “uk ” = українська , “en” = англійська, “ru” = російська	optional
attribute4Type	String	Тип даних для атрибуту. Можливі значення: “N” - число, “C” - текст, “D” - дата у фоматі "dd.MM.yyyy".	optional
attribute4Size	String	Максимальний розмір поля.	optional
attribute4ForInfo	boolean	При значенні true означає, що поле не має бути показане	optional
imageUrl	String	URL з зображенням для даної компанії	optional
needRedirect	boolean	Визначає, чи потрібен перехід на сайт для оплати даної компанії.	required
gateway	PayeeLocalizedTitle	URL для оплати даної компанії. Містить варіанти для 3 мов за ключами: “uk ” = українська, “en” = англійська, “ru” = російська	optional

Приклад:

let payeeService = PayeeService()
payeeService.getPayees { models, error in
            if models != nil {
                self.payees = models
                self.tableView.reloadData()
            } else {
                let code = (error as NSError?)?.code
                self.presentAlert(title: "Error \(code ?? 0)",
                                  message: error?.localizedDescription)
            }
        }

6. Оплата (PayeePaymentService)

Сервіс дозволяє здійснювати оплати по компаніях. Ініціалізується з делегат об’єктом, що підписаний на протокол PayeePaymentDelegate.

Оплата

PayeePaymentService

public func getCommission(commissionParams: CommissionParams,
                          payeeId: String,
                          completion: @escaping PayeePaymentCompletion)

public func proceedPayment(paymentParams: PaymentParams,
                           transaction: PayeePaymentTransaction)

public func startVerify2dCard(transaction: PayeePaymentTransaction,
                              cvv2: String)

public func finishVerify2dCard(transaction: PayeePaymentTransaction,
                               verificationCode: String)

Об’єкт PayeePaymentTransaction

Поле	Тип	Опис
payeeId	String	Ід компанії в системі Portmone.
card	MasterpassCard	Об’єкт карти мастерпасу отриманої за допомогою *CardsService*.
billAmount	Double	Сума до оплати.
commission	Double	Комісія для поточного платежу
bill	Bill	Об’єкт з інформацією про здійснену оплату, заповнюється після успішного завершення оплати.

Об’єкт Bill

Поле	Тип	Опис	Nullability
billId	String	Унікальне ід здійсненої оплати.	optional
recieptUrl	String	Посилання на pdf з квитанцією.	optional
contractNumber	String	Номер особового рахунку.	optional
payDate	Date	Час здійсненої оплати в мілісекундах.	optional

6.1 Отримання комісії (getCommission)

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

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

Параметр	Тип	Опис
commissionParams	CommissionParams	Набір параметрів, необхідних для отримання комісії.
payeeId	String	Ідентифікатор компанії, на яку здійснюється оплата в системі Портмоне.
completion	PayeePaymentCompletion	Асинхронний колбек з результатом отримання комісії.

Об’єкт CommissionParams

Поле	Тип	Опис	Nullability
card	MasterpassCard	Об’єкт карти мастерпасу, отриманої за допомогою *CardService*.	required
billAmount	Double	Сума до оплати, не повинна бути меншою 0.	required
merchantLogin	String	Логін для оплати даної компанії	required
billNumber	String	Унікальний згенерований номер рахунку.	required

PayeePaymentCompletion

public typealias PayeePaymentCompletion = (PayeePaymentTransaction?, Error?) -> Void

Параметри PayeePaymentCompletion

Параметри	Опис
PayeePaymentTransaction?	Об’єкт транзакції. Повертається в разі успішного отримання комісії
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

6.2 Проведення оплати (proceedPayment)

Другий крок після отримання комісії даний метод. Починає процес оплати, результат повернеться в один з методів делегата, що був переданий в ініціалізатор PayeePaymentService.

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

Параметр	Тип	Опис
transaction	PayeePaymentTransaction	Об’єкт транзакції, отриманий з *PayeePaymentCompletion*.
paymentParams	PayeeParams	Об’єкт з набором параметрів необхідних для оплати.

Об’єкт PaymentParams

Поле	Тип	Опис	Nullability
contractNumber	String	Номер особового рахунку (*)	required
attribute1	String	Атрибут оплати 1. (*)	optional
attribute2	String	Атрибут оплати 2. (*)	optional
attribute3	String	Атрибут оплати 3. (*)	optional
attribute4	String	Атрибут оплати 4. (*)	optional
email	String	Електронна пошта, на яку буде вислана квитанція.	optional

* Поля contractNumber, attribute1-4 повинні відповідати полям об’єкта Payee і заповнені у відповідному порядку.

PayeePaymentDelegate

func didFinishPayment(transaction: PayeePaymentTransaction)

func paymentIsWaitingFor2dVerification(transaction: PayeePaymentTransaction)

func paymentIsWaitingFor3dVerification(webView: PortmoneWebView)

func paymentIsFinishedFor3dVerification(webView: PortmoneWebView)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
didFinishPayment	PayeePaymentTransaction	Викликається в разі успішного проведення оплати. Транзакція заповнена об’єктом *Bill*.
paymentIsWaitingFor2dVerification	PayeePaymentTransaction	Викликається в разі необхідності 2д верифікації карти.
paymentIsWaitingFor3dVerification	PortmoneWebView	Викликається в разі необхідності 3д верифікації карти. І приймає UIView з інтегрованою WebView.
paymentIsFinishedFor3dVerification	PortmoneWebView	Викликається після завершення 3д верифікації карти. І приймає UIView з інтегрованою WebView.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

6.3 Верифікація 2д карти (startVerify2dCard, finishVerify2dCard)

Проведення 2д верифікації відбувається в 2 етапи. Перший відбувається при виклику startVerify2dCard, де відбувається перевірка та валідація карти, після його успішного завершення на номер телефону, прив’язаного до карти, прийде смс з кодом верифікації, який необхідний для finish2dVerification. При успішному результаті останнього оплата успішно завершується.

Верифікація 2д карти

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

Параметр	Тип	Опис
transaction	PayeePaymentTransaction	Об’єкт транзакції, отриманий з методу делегата *paymentIsWaitingFor2dVerification*.
cvv2	String	CVV код карти, якій необхідна верифікація.

PayeePaymentDelegate

func verificationIsWaitingForFinish(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
verificationIsWaitingForFinish	PayeePaymentTransaction	Викликається в разі успішного початку 2д верифікації. На номер телефону відсилається смс з кодом для верифікації.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

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

Параметр	Тип	Опис
transaction	PayeePaymentTransaction	Об’єкт транзакції, отриманий з методу делегата *verificationIsWaitingForFinish*.
verificationCode	String	Код верифікації отриманий в смс.

PayeePaymentDelegate

func didFinishPayment(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
didFinishPayment	PayeePaymentTransaction	Викликається в разі успішного завершення верифікації та успішного проведення оплати.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

6.4 Верифікація 3д карти (PortmoneWebView)

Виклик методу paymentIsWaitingFor3dVerification з PayeePaymentDelegate означає, що для проведення оплати даною картою необхідна 3д верифікація, яка відбувається за допомогою PortmoneWebView.

Об’єкт PortmoneWebView приймається як параметр метода делегата, його потрібно розмістити на екрані і показати юзеру.

Верифікація 3д карти

final class Confirm3DCodeViewController: BaseViewController {

    var webView: PortmoneWebView?

    override func viewDidLoad() {
        super.viewDidLoad()

    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)

        guard let webView = webView else {
            return
        }
        addViewToSelf(webView)
    }

    private func addViewToSelf(_ view: UIView) {
        view.translatesAutoresizingMaskIntoConstraints = false
        self.view.addSubview(view)

        NSLayoutConstraint.activate([view.leftAnchor.constraint(equalTo: self.view.leftAnchor),
                                     view.rightAnchor.constraint(equalTo: self.view.rightAnchor),
                                     view.topAnchor.constraint(equalTo: self.view.topAnchor),
                                     view.bottomAnchor.constraint(equalTo: self.view.bottomAnchor)])
    }

    @IBAction private func cancelButtonClicked(_ sender: UIBarButtonItem) {
        presentingViewController?.dismiss(animated: true, completion: nil)
    }
}

PayeePaymentDelegate

func paymentIsFinishedFor3dVerification(webView: PortmoneWebView)

func didFinishPayment(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
paymentIsFinishedFor3dVerification	PortmoneWebView	Викликається незалежно від результату перевірки, щоб прибрати webView з екрану.
didFinishPayment	PayeePaymentTransaction	Викликається в разі успішного завершення верифікації та успішного проведення оплати.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

7. Поповнення мобільного (TopUpMobileService)

Сервіс дозволяє здійснювати поповнення мобільного.

Поповнення мобільного

TopUpMobileService

public func getCommission(commissionParams: CommissionParams,
                          phoneNumber: String,
                          completion: @escaping TopUpCompletion)

public func proceedPayment(paymentParams: PaymentParams,
                           transaction: TopUpMobileTransaction)

public func startVerify2dCard(transaction: TopUpMobileTransaction,
                              cvv2: String)

public func finishVerify2dCard(transaction: TopUpMobileTransaction,
                               verificationCode: String)

Об’єкт TopUpMobileTransaction

Поле	Тип	Опис	Nullability
card	MasterpassCard	Об’єкт карти мастерпас, отриманої за допомогою *CardsService*.	required
billAmount	Double	Сума до оплати.	required
phoneNumber	String	Номер телефону, на який здійснюється поповнення.	required
commission	Double	Комісія для поточного платежу.	required
payeeId	String	Ід компанії в системі Portmone.	required
bill	Buill	Об’єкт з інформацією про здійснену оплату, заповнюється після успішного завершення оплати.	optional

Об’єкт Bill

Поле	Тип	Опис	Nullability
billId	String	Унікальне ід здійсненої оплати.	optional
recieptUrl	String	Посилання на pdf з квитанцією.	optional
contractNumber	String	Номер особового рахунку.	optional
payDate	long	Час здійсненої оплати в мілісекундах.	optional

7.1 Отримання комісії (getCommission)

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

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

Параметр	Тип	Опис
commissionParams	CommissionParams	Набір параметрів, необхідних для отримання комісії.
phoneNumber	String	Номер телефону, на який відбувається поповнення.
completion	TopUpCompletion	Асинхронний колбек з результатом отримання комісії.

Об’єкт CommissionParams

Поле	Тип	Опис	Nullability
card	MasterpassCard	Об’єкт карти мастерпасу, отриманої за допомогою *CardsService*.	required
billAmount	Double	Сума до оплати, не повинна бути меншою 0.	required
merchantLogin	String	Логін для оплати даної компанії.	required
billNumber	String	Унікальний згенерований номер рахунку.	required

PayeePaymentCompletion

public typealias TopUpCompletion = (TopUpMobileTransaction?, Error?) -> Void

Параметри PayeePaymentCompletion

Параметри	Опис
TopUpMobileTransaction?	Об’єкт транзакції. Повертається в разі успішного отримання комісії.
Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

7.2 Проведення оплати (proceedPayment)

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

Параметр	Тип	Опис
transaction	TopUpMobileTransaction	Об’єкт транзакції, отриманий з *TopUpCompletion*.
paymentParams	PayeeParams	Об’єкт з набором параметрів, необхідних для оплати.

Об’єкт PaymentParams

Поле	Тип	Опис	Nullability
contractNumber	String	Номер особового рахунку (*)	required
attribute1	String	Атрибут оплати 1. (*)	optional
attribute2	String	Атрибут оплати 2. (*)	optional
attribute3	String	Атрибут оплати 3. (*)	optional
attribute4	String	Атрибут оплати 4. (*)	optional
email	String	Електронна пошта, на яку буде вислана квитанція.	optional

* Поля contractNumber, attribute1-4 повинні відповідати полям об’єкта Payee і заповнені у відповідному порядку.

PayeePaymentDelegate

func didFinishPayment(transaction: TopUpMobileTransaction)

func paymentIsWaitingFor2dVerification(transaction: TopUpMobileTransaction)

func paymentIsWaitingFor3dVerification(webView: PortmoneWebView)

func paymentIsFinishedFor3dVerification(webView: PortmoneWebView)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
didFinishPayment	TopUpMobileTransaction	Викликається в разі успішного проведення оплати. Транзакція заповнена об’єктом *Bill*.
paymentIsWaitingFor2dVerification	TopUpMobileTransaction	Викликається в разі необхідності 2д верифікації карти.
paymentIsWaitingFor3dVerification	PortmoneWebView	Викликається в разі необхідності 3д верифікації карти. І приймає UIView з інтегрованою WebView.
paymentIsFinishedFor3dVerification	PortmoneWebView	Викликається після завершення 3д верифікації карти. І приймає UIView з інтегрованою WebView.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

7.3 Верифікація 2д карти (startVerify2dCard, finishVerify2dCard)

Проведення 2д верифікації відбувається в 2 етапи. Перший відбувається при виклику startVerify2dCard, де відбувається перевірка та валідація карти, після його успішного завершення на номер телефону прив’язаного до карти прийде смс з кодом верифікації, який необхідний для finish2dVerification. При успішному результаті останнього оплата успішно завершується.

Верифікація 2д карти

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

Параметр	Тип	Опис
transaction	TopUpMobileTransaction	Об’єкт транзакції, отриманий з методу делегата *paymentIsWaitingFor2dVerification*.
cvv2	String	CVV код карти, якій необхідна верифікація.

PayeePaymentDelegate

func verificationIsWaitingForFinish(transaction: TopUpMobileTransaction)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
verificationIsWaitingForFinish	TopUpMobileTransaction	Викликається в разі успішного початку 2д верифікації. На номер телефону відсилається смс з кодом для верифікації.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

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

Параметр	Тип	Опис
transaction	TopUpMobileTransaction	Об’єкт транзакції, отриманий з методу делегата *verificationIsWaitingForFinish*.
verificationCode	String	Код верифікації, отриманий в смс.

PayeePaymentDelegate

func didFinishPayment(transaction: TopUpMobileTransaction)

func didFinishPayment(with error: Error?)

Методи PayeePaymentDelegate

Метод	Параметри	Опис
didFinishPayment	TopUpMobileTransaction	Викликається в разі успішного завершення верифікації та успішного проведення оплати.
didFinishPayment	Error?	Викликається при виникненні помилки під час даної операції. Параметром може бути системна помилка або об’єкт протоколу Error.

7.4 Верифікація 3д карти (PortmoneWebView)

Виклик методу paymentIsWaitingFor3dVerification з TopUpMobileServiceDelegate означає, що для проведення оплати даною картою необхідна 3д верифікація, яка відбувається за допомогою PortmoneWebView.

Об’єкт PortmoneWebView приймається як параметер метода делегата, його потрібно розмістити на екрані і показати юзеру.

Верифікація 3д карти

final class Confirm3DCodeViewController: BaseViewController {

    var webView: PortmoneWebView?

    override func viewDidLoad() {
        super.viewDidLoad()

    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)

        guard let webView = webView else {
            return
        }
        addViewToSelf(webView)
    }

    private func addViewToSelf(_ view: UIView) {
        view.translatesAutoresizingMaskIntoConstraints = false
        self.view.addSubview(view)

        NSLayoutConstraint.activate([
            view.leftAnchor.constraint(equalTo: self.view.leftAnchor),
            view.rightAnchor.constraint(equalTo: self.view.rightAnchor),
            view.topAnchor.constraint(equalTo: self.view.topAnchor),
            view.bottomAnchor.constraint(equalTo: self.view.bottomAnchor)])
    }

    @IBAction private func cancelButtonClicked(_ sender: UIBarButtonItem) {
        presentingViewController?.dismiss(animated: true, completion: nil)
    }
}

8. Список можливих помилок

Внутрішні помилки SDK

Code	Description
2000	Authorization error. Please call AuthorizationService#authorize() before.
2004	Bill amount cannot be less than 0.
2005	Phone number is invalid.
2006	Phone number cannot be empty.
2007	Transaction object is not valid. Please use transaction from proceedPayment() call.
2008	Transaction object is not valid.Please use transaction from getCommission() call.
2009	Verification code cannot be empty.
2010	PayeeId cannot be empty.
2011	Contract number cannot be empty.
2012	User id cannot be empty.
2013	No gate type found for this payee. Payment cannot be proceeded!
2014	Transaction object is not valid.Please use transaction from startVerify2dCard() call.
2015	CVV cannot be empty.
2016	Initialized params cannot be empty. Please call initialize method
2017	Merchant login cannot be empty.
2018	Card verification error.

Також можливі помилки серверу Portmone, у тому ж форматі.

Помилки Masterpass

Code	Description
2100	Internal Error
2101	Connection Error
2102	Card Number is empty
2103	Card Number is invalid
2104	CVV/CVC2 is empty
2105	CVV/CVC2 is invalid
2106	Card Name is empty
2107	Validation Code is empty
2108	Validation Code is invalid
2109	3D URL is empty
2110	3D Secure is not validated
2111	Terms & Condition checkbox is not selected
2112	Expire Year is invalid
2113	OTP sending card's Bank is required.
2114	MasterPass OTP is required for phone number validation.
2200	*Серверна помилка сервісу Masterpass.