218 lines
8.9 KiB
Markdown
218 lines
8.9 KiB
Markdown
|
# ПСКБ Платежи iOS SDK
|
|||
|
|
|||
|
[![Platform](https://img.shields.io/badge/Support-iOS%2010.0+-brightgreen.svg)](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 - обработка закрытия модуля оплаты.
|
|||
|
|
|||
|
## Описание классов и параметров
|