218 lines
8.9 KiB
Markdown
218 lines
8.9 KiB
Markdown
# ПСКБ Платежи iOS SDK
|
||
|
||
[](https://img.shields.io/badge/Support-iOS%2010.3+-brightgreen.svg)
|
||
|
||
Библиотека является дополнением к API системы интернет-эквайринга [ПСКБ "Платежи"](https://online.pscb.ru)
|
||
и позволяет подключить приём платежей по картам в мобильных приложениях iOS с минимальными усилиями.
|
||
|
||
## Возможности
|
||
|
||
На текущий момент библиотека поддерживает:
|
||
|
||
- Apple Pay
|
||
- Оплата картами
|
||
|
||
## Подключение зависимостей
|
||
|
||
1. Установите CocoaPods 1.10.0 или выше
|
||
|
||
```zsh
|
||
gem install cocoapods
|
||
```
|
||
[Официальная документация по установке CocoaPods](https://guides.cocoapods.org/using/getting-started.html)
|
||
|
||
2. Создайте в своём приложении `Podfile`
|
||
|
||
Это также можно сделать при помощи команды `pod init` , находясь в директории своего проекта. (В таком случае будет создан `Podfile` с настройками по умолчанию)
|
||
|
||
3. Добавьте зависимости в `Podfile`
|
||
|
||
```ruby
|
||
platform :ios, '10.0'
|
||
|
||
target '<Target name>' do
|
||
use_frameworks!
|
||
|
||
pod 'PSCBOnline', :git => "https://git2dev.pscb.ru/pscb-dev/pscbonline-ios", :tag => "1.0.0"
|
||
|
||
end
|
||
```
|
||
|
||
> `<Target name>` - Название проекта вашего приложения в XCode
|
||
|
||
4. Выполните команду `pod install`
|
||
|
||
## Интеграция
|
||
|
||
1. Для работы с библиотекой импортируйте зависимости в нужный файл проекта:
|
||
|
||
```swift
|
||
import PSCBOnline
|
||
```
|
||
|
||
2. Создайте экземпляр `PSCBOnlineClient` с вашими настройками:
|
||
|
||
```swift
|
||
let apiClient = PSCBOnlineClient(
|
||
environment: .sandbox,
|
||
marketPlaceId: "<Your MarketPlace ID>",
|
||
signingKey: "<Your Signing Key>"
|
||
)
|
||
```
|
||
|
||
> `environment` - окружение, в рамках которого библиотека взаимодействует с сервисом. `.sandbox` - тестовое окружение; `.production` - продуктовое.
|
||
> `Your MarketPlace ID` - ваш идентификатор в системе ПСКБ-Онлайн.
|
||
> `Your Signing Key` - ваш ключ подписи запросов к системе.
|
||
|
||
3. Создайте экземпляр `Payment`
|
||
|
||
```swift
|
||
let payment = Payment(amount: Decimal(1000.00), orderId: "Order-ID")
|
||
```
|
||
> `amount` - сумма в рублях. (_На текущий момент другая валюта не поддерживается._)
|
||
> `orderId` - уникальный идентификатор заказа в рамках магазина.
|
||
|
||
_Для детальной информации, какие параметры принимает смотрите документацию `Payment`._
|
||
|
||
----
|
||
|
||
Дальнейшая интеграция отличается от способа оплаты.
|
||
|
||
## Доступные способы оплаты
|
||
|
||
Сейчас в SDK доступна оплата:
|
||
|
||
- Банковкой кратой
|
||
- Apple Pay
|
||
|
||
Для их настройки реализации смотрите дальше.
|
||
|
||
### Приём оплаты банковскимикартами
|
||
|
||
1. Для приёма оплаты картами нужно создать экземпляр класса `CardData`.
|
||
|
||
```swift
|
||
let card = CardData(
|
||
pan: "4761349750010326",
|
||
expiryYear: 2022,
|
||
expiryMonth: 12,
|
||
cvCode: "851"
|
||
)
|
||
```
|
||
|
||
2. Создать токен запроса, используя экземпляр `PSCBOnlineClient`, созданный ранее.
|
||
|
||
```swift
|
||
let request = try! client.makeRequestWithCardData(card: card, payment: payment)
|
||
```
|
||
|
||
3. Отправить токен запроса на сервер ПСКБ-Онлайн.
|
||
|
||
```swift
|
||
// Send request to backend
|
||
client.send(request, responseHandler: { (error, response) in
|
||
guard nil == error && nil != response else {
|
||
print("Error sending request: \(String(describing: error))")
|
||
return
|
||
}
|
||
|
||
print("Successful request:")
|
||
print(response!)
|
||
})
|
||
```
|
||
|
||
> В случае успешного выполнения запроса, `response` будет содержать информацию о принятом платеже, его ID, состояние и прочие данные.
|
||
|
||
### Приём оплаты Apple Pay
|
||
|
||
Для приёма платежей через Apple Pay вы должны зарегестрировать Merchant ID в Apple.
|
||
|
||
Помимо `merchant ID` необходимо настроить сертификат обработки запросов (`Payment Processing Certificate`) и передать его ПСКБ-Онлайн. Этим сертификатом Apple будет шифровать данные банковских карт перед отправкой на сервер ПСКБ-Онлайн.
|
||
|
||
Все пререквизиты описаны на сайте [официальной документации Apple](https://developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay_requirements).
|
||
|
||
Также вы можете ознакомиться сподробной инструкцией на сайте документации [ПСКБ Онлайн](https://docs.pscb.ru/oos/advanced.html#dopolnitelnye-opcii-apple-pay).
|
||
|
||
---
|
||
|
||
После выполнения пререквизитов, в коде необходимо:
|
||
|
||
1. Импортировать `PassKit`:
|
||
|
||
```swift
|
||
import PassKit
|
||
```
|
||
|
||
2. Создать экземпляр класса `PKPaymentAuthorizationController` и настроить делегирующий класс `PKPaymentAuthorizationControllerDelegate`:
|
||
|
||
Пример:
|
||
|
||
```swift
|
||
import PassKit
|
||
import PSCBOnline
|
||
|
||
class ApplePayHandler: NSObject {
|
||
|
||
public func handleApplePay(payment: Payment) {
|
||
// Позиции оплаты для представления пользователя
|
||
let items = [PKPaymentSummaryItem(label: "Shoes", amount: NSDecimalNumber(intergerLiteral: 1000))]
|
||
|
||
// Запрос на оплату для PKPaymentAuthorizationController
|
||
let paymentRequest = PSCBAPI.makePaymentRequest(merchantId: "<Your Apple Merchant ID>", items: [])
|
||
|
||
// Вызов модуля оплаты
|
||
let authorizationController = PKPaymentAuthorizationController(paymentRequest: paymentRequest)
|
||
|
||
authorizationController?.delegate = self
|
||
authorizationController?.present(completion: { presented in
|
||
if presented {
|
||
print("Controller presented")
|
||
} else {
|
||
print("Controller could not be presented")
|
||
}
|
||
})
|
||
}
|
||
}
|
||
|
||
extension ApplePayHandler: PKPaymentAuthorizationControllerDelegate {
|
||
|
||
public func paymentAuthorizationController(_ controller: PKPaymentAuthorizationController,
|
||
didAuthorizePayment payment: PKPayment,
|
||
handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
|
||
|
||
// 1.
|
||
// Вызывается после авторизации платежа плательщиком биометрическими данными или паролем
|
||
}
|
||
|
||
public func paymentAuthorizationControllerDidFinish(_ controller: PKPaymentAuthorizationController) {
|
||
// 2.
|
||
// Вызывается после того, как платёж совершён или пользователь закрыл модуль оплаты.
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
> `<Your Apple Merchant ID>` - Ваш идентификатор мерчанта.
|
||
|
||
3. Далее в примере выше в п.1 и п.2 реализовать необходимую логику отправки запроса на сервер ПСКБ-Онлайн.
|
||
Для пункта 1 - это создание токена запроса (используя `client.makeRequestWithPayment(pkPayment, pscbPayment)` и отправка его на сервер:
|
||
|
||
```swift
|
||
// Request token
|
||
let request = try! client.makeRequestWithPayment(pkPayment: pkPayment, pscbPayment: payment)
|
||
|
||
// Sending request to backend
|
||
client.send(request, responseHandler: { (error, response) in
|
||
if (error == nil && response != nil) {
|
||
completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
|
||
} else {
|
||
print("Error sending payment: \(String(describing: error))")
|
||
completion(PKPaymentAuthorizationResult(status: .failure, errors: nil))
|
||
}
|
||
})
|
||
```
|
||
|
||
4. А для пункта 2 - обработка закрытия модуля оплаты.
|
||
|
||
## Описание классов и параметров
|