pscbonline-ios/README.md

#  ПСКБ Платежи 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 - обработка закрытия модуля оплаты.

## Описание классов и параметров