iOS SDK (iOS, Swift)
PayBox SDK iOS - это библиотека позволяющая упростить взаимодействие с API PayBox.
PayBox SDK iOS - это библиотека позволяющая упростить взаимодействие с API PayBox.
Описание возможностей:
- Инициализация платежа
- Отмена платежа
- Возврат платежа
- Проведение клиринга
- Проведение рекуррентного платежа с сохраненными картами
- Получение информации/статуса платежа
- Добавление карт/Удаление карт
- Оплата добавленными картами
- Безакцептные платежи
- Оплата с помощью Apple Pay
Установка:
- Чтобы интегрировать "PayBoxSdk"; в проект 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)
}