iOS SDK (iOS, Swift)

SDK iOS - это библиотека позволяющая упростить взаимодействие с API.

Описание возможностей:

Инициализация платежа
Отмена платежа
Возврат платежа
Проведение клиринга
Проведение рекуррентного платежа с сохраненными картами
Получение информации/статуса платежа
Добавление карт/Удаление карт
Оплата добавленными картами
Безакцептные платежи
Оплата с помощью Apple Pay

Установка:

Чтобы интегрировать "Sdk"; в проект Xcode с использованием "Cocoapods", добавьте в Podfile:

        target 'Project name' do
            pod 'PayBoxSdk', :git => 'https://github.com/PayBox/SDK_iOS-input-.git', :submodules => true
        end

2. Затем выполните след. команду:

        $ pod install

Для связи с SDK

1. Инициализация SDK:

    let sdk = PayboxSdk.initialize(merchantId: merchantID, secretKey: "secretKey")

2. Добавьте PaymentView в ваш UIViewController:

    let paymentView = PaymentView(frame: CGRect(x: 0, y: 0, width: width, height: height))

3. Передайте экземпляр paymentView в sdk:

    sdk.setPaymentView(paymentView: paymentView)

4. Для отслеживания прогресса загрузки платежной страницы используйте WebDelegate:

    paymentView.delegate = self

    func loadStarted() {

    }
    func loadFinished() {

    }

Настройки SDK

Тестовый режим:

    sdk.config().testMode(enabled: true) // По умолчанию тестовый режим включен

Выбор региона:

    sdk.config().setRegion(region: .DEFAULT) //Region.DEAFAULT по умолчанию

Класс Region имеет следующие значения:

Выбор платежной системы:

    sdk.config().setPaymentSystem(paymentSystem: paymentSystem)

Выбор валюты платежа:

    sdk.config().setCurrencyCode(code: "KZT")

Активация автоклиринга:

    sdk.config().autoClearing(enabled: enabled)

Установка кодировки:

    sdk.config().setEncoding(encoding: "UTF-8") // по умолчанию UTF-8

Время жизни рекурентного профиля:

    sdk.config().setRecurringLifetime(lifetime: 36) //по умолчанию 0 месяцев (параметр исключается из списка при значении 0)

Время жизни платежной страницы, в течение которого платеж должен быть завершен:

    sdk.config().setPaymentLifetime(lifetime: 300)  //по умолчанию 300 секунд

Включение режима рекурентного платежа:

    recurringMode(enabled: enabled)  //по умолчанию отключен

Номер телефона клиента, будет отображаться на платежной странице. Если не указать, то будет предложено ввести на платежной странице:

    sdk.config().setUserPhone(userPhone: userPhone)

Email клиента, будет отображаться на платежной странице. Если не указать email, то будет предложено
ввести на платежной странице:

    sdk.config().setUserEmail(userEmail: email)

Язык платежной страницы:

    sdk.config().setLanguage(language: .ru)

Для передачи информации от платежного гейта:

    sdk.config().setCheckUrl(url: url)
    sdk.config().setResultUrl(url: url)
    sdk.config().setRefundUrl(url: url)
    sdk.config().setClearingUrl(url: url)
    sdk.config().setRequestMethod(requestMethod: requestMethod)

Для выбора Frame вместо платежной страницы:

    sdk.config().setFrameRequired(isRequired: true) //false по умолчанию

Работа с SDK

Создание платежа:

    sdk.createPayment(amount: amount, description: "description", orderId: "orderId", userId: userId, extraParams: extra) {
            payment, error in   //Вызовется после оплаты
    }

После вызова в paymentView откроется платежная страница

Рекурентный платеж:

    sdk.createRecurringPayment(amount: amount, description: "description", recurringProfile: "profile", orderId: "orderId", extraParams: extra) {
            recurringPayment, error in // Вызовется после оплаты
    }

Получение статуса платежа:

    sdk.getPaymentStatus(paymentId: paymentId) {
            status, error in // Вызовется после получения ответа
    }

Клиринг платежа:

    sdk.makeClearingPayment(paymentId: paymentId, amount: amount) {  // Если указать nil вместо суммы клиринга, то клиринг пройдет на всю сумму платежа
            capture, error in // Вызовется после клиринга
    }

Отмена платежа:

    sdk.makeCancelPayment(paymentId: paymentId) {
            payment, error in // Вызовется после отмены
    }

Возврат платежа:

    sdk.makeRevokePayment(paymentId: paymentId, amount: amount) {
            payment, error in // Вызовется после возврата
    }

Сохранение карты:

    sdk.addNewCard(postLink: url, userId: userId) {
            payment, error in // Вызовется после сохранения
    }

После вызова в paymentView откроется платежная страница

Получить список сохраненых карт:

    sdk.getAddedCards(userId: userId) {
            cards, error in // Вызовется после получения ответа
    }

Удаление сохраненой карты:

    sdk.removeAddedCard(cardId: cardId, userId: userId) {
            payment, error in // Вызовется после ответа
    }

Создание платежа сохраненой картой:

    sdk.createCardPayment(amount: amount, userId: userId, cardToken: "cardToken", description: "description", orderId: "01234", extraParams: nil) {
            payment, error in // Вызовется после создания
    }

Внимание: Метод createCardPayment с использованием cardId является устаревшим.

Для оплаты созданного платежа:

    sdk.payByCard(paymentId: paymentId) {
            payment, error in // Вызовется после оплаты
    }

После вызова в paymentView откроется платежная страница для 3ds аутентификации

Для оплаты созданного платежа c безакцепным списанием:

   sdk.createNonAcceptancePayment(paymentId: paymentId){
            payment, error -> //Вызовется после оплаты
   }

Интеграция Apple Pay

В первую очередь необходимо создать идентификатор мерчанта и настроить сертификат обработки платежей в консоли разработчика согласно документации на официальном сайте PassKit. После чего можно перейти к настройке проекта и самой интеграции:

1. Включите поддержку Apple Pay для вашего проекта в Xcode

В окне навигации вашего проекта выделите файл проекта
Выберите ваше приложение в меню TARGET
Перейдите во вкладку Signing & Capabilities
В верхнем меню нажмите кнопку + для того что бы добавить поддержку библиотеки Apple Pay
В добавленном разделе библиотеки Apple Pay необходимо нажать кнопку обновить для синхронизации идентификаторов мерчанта с сайта Apple Developer.
Выберите необходимый идентификатор мерчанта для работы с вашим приложением.

2. Импортируйте PassKit в ваш контроллер:

   import PassKit

3. Добавьте проверку состояния Apple Pay на устройстве:

    func applePayStatus() -> (canMakePayments: Bool, canSetupCards: Bool) {
        return (PKPaymentAuthorizationController.canMakePayments(),
                PKPaymentAuthorizationController.canMakePayments(usingNetworks: supportedNetworks))
    }

4. Задайте список поддерживаемых МПС:

    let supportedNetworks: [PKPaymentNetwork] = [
        .masterCard,
        .visa
    ]

5. Добавьте метод который подготавливает данные для оплаты и отображает контроллер Apple Pay:

    @objc func initApplePay(_: AnyObject) {
        // Товары в корзине
        let item1 = PKPaymentSummaryItem(label: "Item 1", amount: NSDecimalNumber(string: "4.00"), type: .final)
        let item2 = PKPaymentSummaryItem(label: "Item 2", amount: NSDecimalNumber(string: "1.00"), type: .final)

        // Наименование магазина и итоговая цена
        let total = PKPaymentSummaryItem(label: "Your company name", amount: NSDecimalNumber(string: "5.00"), type: .final)

        let paymentSummaryItems = [item1, item2, total]

        // Подготовка запроса оплаты Apple Pay
        let paymentRequest = PKPaymentRequest()
        paymentRequest.paymentSummaryItems = paymentSummaryItems
        paymentRequest.merchantIdentifier = "your_merchant_identifier" // заменить на актуальный MerchantID из консоли разработчика Apple
        paymentRequest.merchantCapabilities = .threeDSecure
        paymentRequest.countryCode = "KZ"
        paymentRequest.currencyCode = "KZT"
        paymentRequest.supportedNetworks = supportedNetworks
        
        // Отображение контроллера Apple Pay
        let paymentController = PKPaymentAuthorizationController(paymentRequest: paymentRequest)
        paymentController.delegate = self
        paymentController.present(completion: { (presented: Bool) in
            if presented {
                debugPrint("Presented payment controller")
            } else {
                debugPrint("Failed to present payment controller")
            }
        })
    }

6. Добавьте метод для инициализации и подтверждения платежа с помощью SDK:

func finishApplePayPayment(tokenData: Data, handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
        let amount: Float = 5
        let description = "some description"
        let orderId = "1234"
        let userId = "1234"
        
        sdk.createApplePayment(amount: amount, description: description, orderId: orderId, userId: userId, extraParams: nil) {
                    paymentId, error in {
                        self.sdk.confirmApplePayment(paymentId: paymentId ?? "", tokenData: tokenData) {
                            confirmPayment, confirmError in {
                                if let directError = confirmError {
                                    completion(PKPaymentAuthorizationResult(status: .failure, errors: nil))
                                
                                    // Ошибка платежа
                                } else if let directPay = confirmPayment {
                                    completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
                                    
                                    // Успешный платеж
                                }
                            }()
                        }
                    }()
            }
    }

7. Добавьте кнопку Apple Pay на ваш экран

Создаем непосредственно саму кнопку:

   lazy var applePayButton: UIButton! = {
        let button = PKPaymentButton(paymentButtonType: .plain, paymentButtonStyle: .black)
        button.translatesAutoresizingMaskIntoConstraints = false
        button.frame = CGRect.zero
        button.clipsToBounds = true
        button.contentEdgeInsets = UIEdgeInsets(top: 0,left: 10,bottom: 0,right: 10)
        button.backgroundColor = UIColor.black
        button.layer.cornerRadius = 25
        button.layer.borderWidth = 1
        button.layer.borderColor = UIColor.black.cgColor
        
        return button
    }()

Добавляем кнопку во вью:

   self.view.addSubview(applePayButton)

Задаем положение кнопки на экране:

   NSLayoutConstraint.activate([
        applePayButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
        applePayButton.topAnchor.constraint(equalTo: guide.topAnchor, constant: 30),
        applePayButton.widthAnchor.constraint(equalToConstant: 250),
        applePayButton.heightAnchor.constraint(equalToConstant: 50)
   ])

Добавляем вызов функции initApplePay для подготовки платежа и отображении окна Apple Pay при клике на кнопку:

   applePayButton.addTarget(self, action: #selector(self.initApplePay(_:)), for: .touchUpInside)

Для корректной работы необходимо убедиться что Apple Pay настроен на устойстве и управляем состоянием кнопки в зависимости от полученного статуса:

    let applePayStatus = applePayStatus()
    applePayButton.isHidden = !applePayStatus.canMakePayments

8. Наследуйте делегат PKPaymentAuthorizationControllerDelegate:

   class ViewController: UIViewController, WebDelegate, PKPaymentAuthorizationControllerDelegate

9. Имплементируйте методы делегата:

   //Скрываем контроллер Apple Pay самостоятельно
   func paymentAuthorizationControllerDidFinish(_ controller: PKPaymentAuthorizationController) {
       controller.dismiss()
   }
    
    
   //Получаем токен от Apple Pay и передаем в функцию `finishApplePayPayment` для взаимодействия с SDK
   func paymentAuthorizationController(_ controller: PKPaymentAuthorizationController, didAuthorizePayment payment: PKPayment, handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
       finishApplePayPayment(tokenData: payment.token.paymentData, handler: completion)
   }