SDK TipTopPay для iOS

SDK TipTopPay позволяет интегрировать сервис обработки платежей в iOS-приложение.

Требования

iOS версии 13.0 и ниже

Подключение

Для подключения SDK можно использовать Swift Package Manager или CocoaPods.

• Для подключения через Swift Package Manager используйте меню Файл -> Добавить зависимости пакета, найдите SDK по URL-адресу пакета - https://github.com/tiptoppaymobile/TipTopPay-SDK-iOS и добавьте зависимость в проект.

• Для подключения через CocoaPods добавьте зависимости в Podfile:

pod 'TipTopPay', :git =>  "https://github.com/tiptoppaymobile/TipTopPay-SDK-iOS", :branch => "master"
pod 'TipTopPayNetworking', :git =>  "https://github.com/tiptoppaymobile/TipTopPay-SDK-iOS", :branch => "master"

Возможности TipTopPay SDK:

Вы можете использовать SDK одним из трёх способов:

• использовать стандартную платежную форму TipTopPay с уже готовым интерфейсом и коробочными решениями для оплаты
• реализовать платежную форму со своим визуалом с оплатой через готовые функции TipTopPayApi, которые позволяют оплатить любым из доступных методов
• реализовать платежную форму со своим визуалом с возможностью оплаты через ваш сервер. Что позволит помимо всего сохранять криптограммы на своем сервере для отложенной оплаты

Структура проекта

• demo - Пример приложения, использующего SDK
• sdk - Исходный код SDK

Локализация

Если вам необходима локализация, добавьте «Localizable.strings» в целевые языки вашего приложения (английский, русский, казахский).

Использование формы оплаты в SDK TipTopPay:

1. Создайте объект TipTopPayDataPayer и инициализируйте его, затем создайте объект PaymentData. Передайте в него объект TipTopPayDataPayer, сумму платежа, валюту и дополнительные данные. Если вы хотите использовать Apple Pay, также передайте идентификатор продавца Apple Pay.

// Дополнительный параметр для данных клиента. Используйте следующие параметры: Имя, Фамилия, Отчество, Дата рождения, Улица, Адрес, Город, Страна, Телефон, Почтовый индекс
let payer = PaymentDataPayer(firstName: "", lastName: "", middleName: "", birth: "1955-02-22", address: "home 6", street: "Baker street", city: "London", country: "KZT", phone: "39991234567", postcode: "123456")

// Укажите дополнительные данные, если необходимо
let jsonData: [String: Any] = ["age":27, "name":"Alex", "phone":"+39998881122"] // Любые другие данные, которые будут связаны с транзакцией, включая инструкции по созданию подписки или генерации онлайн-квитанции, должны быть заключены в объект TipTopPay.

let paymentData = TipTopPayData()

.setAmount(String(totalAmount)) // Сумма платежа, максимум 2 знака после запятой

.setCurrency(.ruble) // Валюта

.setApplePayMerchantId("") // Идентификатор продавца Apple Pay (необходимо получить у Apple)

.setDescription("Корзина цветов") // Описание платежа

.setAccountId("111") // Обязательный идентификатор клиента для создания подписки и получения токена

.setInvoiceId("123") // Номер заказа или счета

.setEmail("test@tiptoppay.inc") // Адрес электронной почты клиента (используется для отправки подтверждения платежа)

.setPayer(payer) // Информация о клиенте

.setJsonData(jsonData) // Любые другие данные, связанные с этим платежом

2. Создайте объект TipTopPayConfiguration, передайте в него объект PaymentData и ваш Public_id, полученный из личного кабинета TipTopPay. Реализуйте протокол TipTopPayDelegate для получения результата платежа

let configuration = TipTopPayConfiguration(
publicId: "", // Ваш публичный ID, полученный в панели управления
paymentData: paymentData, // Данные платежа
delegate: self, // Отображение информации о завершении платежа
uiDelegate: self, // Отображение информации пользовательского интерфейса
scanner: nil, // Сканер карты
requireEmail: true, // Использование электронной почты (false – не требуется, true – требуется)
useDualMessagePayment: true, // Использование двухстадийных платежей (true). По умолчанию используются одностадийные платежи (false)
disableApplePay: false, // Отключение Apple Pay (включено по умолчанию)

3. Инициализируйте пользовательский интерфейс оплаты внутри вашего контроллера

PaymentForm.present(with: configuration, from: self)

Использование вашей платежной формы с использованием функций TipTopPayApi:

• Для использования нового формата криптограммы:

1. Получите publicKey (Pem) и keyVersion (Version) с данного API

2. Полученные publicKey и keyVersion передайте в метод создания криптограммы Card.makeCardCryptogramPacket, а также merchantPublicId полученный в личном кабинете TipTopPay и данные карты для создания криптограммы

3. Cоздайте криптограмму карточных данных

// Обязательно проверяйте входящие данные карты (номер, срок действия и cvc код) на корректность, иначе метод создания криптограммы вернет nil.
let cardCryptogramPacket = Card.makeCardCryptogramPacket(cardNumber: cardNumber, expDate: expDate, cvv: cvv, merchantPublicID: "Ваш Public_id из личного кабинета", publicKey: "Полученный публичный ключ", keyVersion: "Полученная версия ключа")

4. Выполните запрос на проведения платежа (см. документацию по API).

5. Если необходимо, покажите 3DS форму для подтверждения платежа

let data = ThreeDsData(transactionId: transactionId, paReq: paReq, acsUrl: acsUrl)
let threeDsProcessor = ThreeDsProcessor()
threeDsProcessor.make3DSPayment(with: data, delegate: self)

6. Для получения формы 3DS и получения результатов прохождения 3DS аутентификации реализуйте протокол ThreeDsDelegate.

extension CheckoutViewController: ThreeDsDelegate {
    // Вы получаете объект WKWebView, который сами показываете нужным вам способом и в нужном вам месте
    func willPresentWebView(_ webView: WKWebView) {
        self.showThreeDsForm(webView)
    }

    // threeDsCallbackId - идентификатор, полученный в ответ на запрос на проведение платежа
    // Используйте md и paRes, для завершения оплаты
    func onAuthotizationCompleted(with md: String, paRes: String) {
        hideThreeDs() // метод закрытия 3ds
        // Здесь вызовите свой созданный метод post3ds из пункта 7
    }

    func onAuthorizationFailed(with html: String) {
        hideThreeDs() // метод закрытия 3ds
        print("error: \(html)")
    }
}

7. Выполните запрос post3ds для завершения оплаты (см. документацию по API).

История обновлений:

1.0.13

• Добавлено логирование

1.0.12

• Исправлены делегаты paymentFormWillHide и paymentFormDidHide

1.0.11

• Добавлен Swift Package Manager

1.0.10

• Исправлены ошибки

1.0.9

• Улучшена стабильность

1.0.4

• Добавлено сохранение карты

1.0.3

• Добавлен манифест конфиденциальности

1.0.2

• Улучшена стабильность

1.0.1

• Добавлено объяснение некоторых причин отклонения платежей

1.0.0

• Начальная версия

Поддержка

По возникающим вопросам технического характера обращайтесь на support-kz@tiptoppay.inc