SDK для iOS
SDK для iOS — это набор средств разработки для подключения мобильных приложений, работающих на платформе iOS, к платежной платформе PSPHost. В этом разделе представлена информация о работе с SDK для iOS с примерами кода на языках программирования Swift и Objective-C.
В рамках SDK для iOS 1.9 доступны две версии: SDK для iOS 1.9.1 можно встраивать в мобильные приложения, работающие на платформе iOS версии 11 или выше и совместимые с Xcode версии 11 или выше, а для мобильных приложений, работающих на платформе iOS 10 и совместимых с Xcode 10, необходимо использовать SDK для iOS 1.9.0.
- Библиотеки: https://github.com/psphost/iOS-SDK/releases
- Примеры кода: https://github.com/psphost/iOS-SDK
Общая информация
Возможности
SDK для iOS позволяет проводить платежи с использованием платежных карт, а также альтернативных платежных методов. Для платежей с использованием карт доступны проведение разовых и повторяемых оплат, проверка действительности карт (подробнее).
Также поддерживается проведение платежей с использованием методов, информация о которых представлена в разделе Платежные методы. По вопросам, связанным с подключением этих платежных методов, следует обращаться к курирующему менеджеру PSPHost.
- Поддержка русского и английского языков (русского — при его выборе в настройках мобильного устройства и английского — в остальных случаях; со стороны мерчанта также возможно выбрать язык платежной формы).
- Поддержка индивидуального дизайна и настройка цветового оформления платежной формы (подробнее).
- Поддержка разных способов ввода данных карты (подробнее):
- ручной ввод,
- сканирование карты,
- выбор сохраненной карты,
- использование предварительно выбранной карты.
- Сбор или указание дополнительных данных о пользователе (подробнее).
- Уточнение дополнительных параметров, обязательных для проведения оплаты (подробнее).
- Поддержка аутентификации 3‑D Secure 2. Протокол 3‑D Secure 2 является новой версией протокола 3‑D Secure (Three-Domain Secure), который обеспечивает безопасное проведение интернет-оплат с использованием платежных карт (подробнее).
- Поддержка повторных попыток оплаты в случае ошибок (подробнее).
- Получение информации о платеже: на всех страницах платежной формы доступна кнопка информации, при выборе которой отображаются данные о сумме, идентификаторе и дате проведения платежа, а также описание платежа.
- Отправка электронного товарного чека пользователю (подробнее).
Состав
SDK для iOS содержит библиотеку, которая задействуется при разработке и использовании приложений на устройствах Apple, и примеры работы на языках программирования Swift и Objective-C.
Схема работы
- В клиентской части мобильного приложения формируется объект с необходимыми параметрами для проведения платежа.
- В серверной части мобильного приложения вычисляется подпись на основании параметров платежа.
- В клиентской части формируется итоговый запрос на проведение платежа и с помощью библиотеки отправляется в платежную платформу PSPHost.
- В платежной платформе выполняется обработка платежа.
- От платежной платформы к клиентской части отправляется результат выполнения платежа.
- От платежной платформы на заданный URL отправляется оповещение.
Подключение и использование
- Решить организационные вопросы, касающиеся взаимодействия с PSPHost:
- Если у компании нет идентификатора и ключа для взаимодействия с PSPHost — отправить заявку на подключение.
- Если у компании есть идентификатор и ключ для взаимодействия с PSPHost — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для iOS и согласовать с ними порядок тестирования и запуска.
- Выполнить подготовительные технические работы:
- Обеспечить подписывание данных на стороне серверной части мобильного приложения.
- Скачать библиотеку SDK для iOS.
- Подключить библиотеку к клиентской части мобильного приложения.
- Доработать клиентскую часть мобильного приложения для инициирования платежей необходимых типов и обработки результатов этих платежей.
- Протестировать и запустить в работу обновленное приложение.
- Для тестирования следует использовать тестовый идентификатор проекта и данные тестовых карт, предоставленные специалистами технической поддержки PSPHost.
- Для перевода в рабочий режим следует изменить тестовое значение идентификатора проекта на рабочее значение, полученное от PSPHost.
При возникновении вопросов о работе с SDK для iOS следует обращаться в службу технической поддержки PSPHost support@psphost.com.
Интерфейс платежной формы







Обеспечение работы с подписью
Для обеспечения защиты информации при взаимодействиях с PSPHost передаваемые сообщения должны подписываться. Получение данных для подписывания должно выполняться в клиентской части приложения с помощью SDK для iOS, а генерация подписи — в серверной части с использованием секретного ключа.
- Вычислить код HMAC для полученной строки на основе алгоритма SHA-512 и секретного ключа.
- Выполнить кодировку результата по алгоритму Base64.
- Строка для подписывания.
customer_id:5;payment_amount:30;payment_currency:RUB;payment_id:payment1;project_id:115
- Значение секретного ключа —
12345
. - Результат генерации подписи.
pVmAtGFBQJD2NgLToP1B2elR4QROiYGi3IobPD9PFDfrkjBqdSCFgrVSEtebVJUzOUUHX5tPnHQq9RMn61679A==
Реализацию алгоритмов следует выбирать с учетом технологий, используемых в серверной части приложения. Подробная информация о генерации подписи представлена в разделе Использовании подписи к данным.
Подключение библиотек
Подключение в Swift
- Перенести файл
psphostSDK.xcframework
в папку проекта мобильного приложения. - Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо:
- Открыть цель (target) проекта.
- Перейти в .
- Щелкнуть +.
- Щелкнуть Add Other.
- Выбрать файл
psphostSDK.xcframework
. - Щелкнуть Add.
- Добавить ключ NSCameraUsageDescription со значением
permission is needed in order to scan card
в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через ее сканирование. -
Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением
fraud prevention
в файл Info.plist.PSPHost не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.
Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.
- Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ Privacy - Photo Library Usage Description и ключ Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных.
Подключение в Objective-C
Для подключения библиотек к проекту мобильного приложения необходимо:
- Перенести файл
psphostSDK.xcframework
в папку проекта мобильного приложения. - Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо:
- Открыть цель (target) проекта.
- Перейти в .
- Щелкнуть +.
- Щелкнуть Add Other.
- Выбрать файл
psphostSDK.xcframework
. - Щелкнуть Add.
- Выбрать раздел Build Settings.
- Установить переключатель Always embed swift embedded libraries в положение Yes.
- Добавить ключ NSCameraUsageDescription со значением
permission is needed in order to scan card
в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через ее сканирование. -
Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением
fraud prevention
в файл Info.plist.PSPHost не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.
Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.
- Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ Privacy - Photo Library Usage Description и ключ Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных.
Вызов платежной формы
Вызов в Swift
Для вызова платежной формы необходимо выполнить следующие действия:
- Импортировать библиотеку.
import psphostSDK
- Объявить библиотеку
psphostSDK
в любом месте приложения (например, внутри методаviewDidLoad
).let psphostSDK = PsphostSDK()
- Создать объект
PaymentInfo
. Этот объект должен содержать обязательные параметры для открытия платежной формы:- projectID — идентификатор проекта, полученный от PSPHost при интеграции;
- paymentID — идентификатор платежа, уникальный в рамках проекта;
- paymentAmount — сумма платежа в дробных единицах валюты без десятичной точки и пробелов;
- paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.
Пример объекта
PaymentInfo
, который содержит только обязательные параметры:let paymentInfo = PaymentInfo(projectID: 10, paymentID: "internal_payment_id_1", paymentAmount: 1999, paymentCurrency: "USD")
Дополнительно могут использоваться следующие объекты и параметры:- recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
- paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платежной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
- customerID — идентификатор пользователя, уникальный в рамках проекта.
- regionCode — код страны пользователя в формате ISO 3166 alpha-2.
- token — токен карты.
- action — тип действия. Допустимые значения:
Sale
(по умолчанию),Auth
,Verify
иTokenize
. - forcePaymentMethod — идентификатор платежного метода, который следует открыть в платежной форме. Если этот параметр задан, то страница выбора метода не отображается и пользователю не предоставляется возможность выбрать платежный метод. Список идентификаторов методов см. в Коды поддерживаемых платежных методов на Payment Page.
- hideSavedWallets — параметр, позволяющий управлять отображением сохраненных ранее платежных инструментов и при необходимости скрывать сохраненные платежные инструменты в платежной форме. Возможные значения:
true
— сохраненные ранее платежные инструменты скрыты, они не отображаются при открытии платежной формы.false
— сохраненные ранее платежные инструменты отображаются при открытии платежной формы.
PsphostScreenDisplayMode
— объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать ее. В объекте необходимо передавать следующие параметры:hide_success_final_page
— финальная страница с сообщением о совершенном платеже не отображается в платежной форме,hide_decline_final_page
— финальная страница с сообщением об отклоненном платеже не отображается в платежной форме.
Пример передачи в запросе параметров
hide_success_final_page
иhide_decline_final_page
:// Init PaymentInfo paymentInfo.addScreenDisplayMode(value: "hide_success_final_page") .addScreenDisplayMode(value: "hide_decline_final_page")
Пример объекта
PaymentInfo
, который содержит необязательные параметры (описание платежа, идентификатор и страну пользователя):let paymentInfo = PaymentInfo(projectID: 10, paymentID: "internal_payment_id_1", paymentAmount: 1999, paymentCurrency: "USD", paymentDescription: "T-shirt with dog print", customerID: "10", regionCode: "US")
- Получить строку для подписывания указанных параметров.
paymentInfo.getParamsForSignature();
- Передать сгенерированную строку в серверную часть приложения.
- Сгенерировать подпись на стороне серверной части приложения и передать ее в клиентскую часть.
- Добавить подпись в объект
PaymentInfo
.paymentInfo.setSignature(value: signature)
- Вызвать платежную форму.
psphostSDK.presentPayment(at: self, paymentInfo: paymentInfo) { (result) in print("psphostSDK finished with status \(result.status.rawValue)") if let error = result.error { // в случае ошибки print("Error: \(error.localizedDescription)") } if let token = result.token { // при генерации токена print("Token: \(token)") } }
После вызова платежной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платежная форма, в других случаях платежная форма не открывается, а метод вызова платежной формы возвращает код ошибки.
Вызов в Objective-C
Для вызова платежной формы необходимо выполнить следующие действия:
- Импортировать библиотеку.
#import <psphostSDK/PsphostSDK.h>
- Объявить библиотеку psphostSDK в любом месте приложения (например, внутри метода
viewDidLoad
).psphostSDK *psphostSDK = [[psphostSDK.h alloc] init];
- Создать объект
PaymentInfo
. Этот объект должен содержать обязательные параметры для открытия платежной формы:- projectID — идентификатор проекта, полученный от PSPHost при интеграции;
- paymentID — идентификатор платежа, уникальный в рамках проекта;
- paymentAmount — сумма платежа в дробных единицах валюты;
- paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.
PaymentInfo
, который содержит только обязательные параметры:PaymentInfo *paymentInfo = [[PaymentInfo alloc] initWithProjectID:10 paymentID:@"internal_payment_id_1" paymentAmount:1999 paymentCurrency:@"USD"];
Дополнительно могут использоваться следующие объекты и параметры:- recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
- paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платежной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
- customerID — идентификатор пользователя, уникальный в рамках проекта.
- regionCode — код страны пользователя в формате ISO 3166 alpha-2.
- token — токен карты.
- ActionType — тип действия. Допустимые значения:
Sale
(по умолчанию),Auth
,Verify
иTokenize
. - forcePaymentMethod — идентификатор платежного метода, который следует открыть в платежной форме. Если этот параметр задан, то страница выбора метода не отображается и пользователю не предоставляется возможность выбрать платежный метод. Список идентификаторов методов приведен в разделе Коды поддерживаемых платежных методов на Payment Page.
- hideSavedWallets — параметр, позволяющий управлять отображением сохраненных ранее платежных инструментов и при необходимости скрывать сохраненные платежные инструменты в платежной форме. Возможные значения:
true
— сохраненные ранее платежные инструменты скрыты, они не отображаются при открытии платежной формы.false
— сохраненные ранее платежные инструменты отображаются при открытии платежной формы.
PsphostScreenDisplayMode
— объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать ее. В объекте возможно передавать следующие параметры:hide_success_final_page
— финальная страница с сообщением о совершенном платеже не отображается в платежной форме,hide_decline_final_page
— финальная страница с сообщением об отклоненном платеже не отображается в платежной форме.
Пример передачи в запросе параметров
hide_success_final_page
иhide_decline_final_page
:// Init PaymentInfo [paymentInfo addScreenDisplayMode: hide_success_final_page]; [paymentInfo addScreenDisplayMode: hide_decline_final_page];
Пример объекта
PaymentInfo
, который содержит необязательные параметры (описание платежа, идентификатор и страну пользователя):PaymentInfo *paymentInfo = [[PaymentInfo alloc] initWithProjectID:10 paymentID:@"internal_payment_id_1" paymentAmount:1999 paymentCurrency:@"USD" paymentDescription:@"T-shirt with dog print" customerID:@"10" regionCode:@"US"];
- Получить строку для подписывания указанных параметров.
paymentInfo.getParamsForSignature();
- Передать сгенерированную строку в серверную часть приложения.
- Сгенерировать подпись на стороне серверной части приложения и передать ее в клиентскую часть.
- Добавить подпись в объект
PaymentInfo
.[paymentInfo setSignature:signature];
- Вызвать платежную форму.
[self.psphostSDK presentPaymentAt:self paymentInfo:paymentInfo completionHandler:^(psphostPaymentResult *result) { NSLog(@"psphostSDK finished with status %ld", (long)result.status); if(result.error != NULL) { // в случае ошибки NSLog(@"Error: %@", result.error.localizedDescription); } if(result.token != NULL) { // при генрации токена NSLog(@"Token: %@", result.token); } }];
После вызова платежной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платежная форма, в других случаях платежная форма не открывается, а метод вызова платежной формы возвращает код ошибки.
Прием результатов
Для получения кода ответа о проведении платежа необходимо задать:
psphostSDK.presentPayment(at: self, paymentInfo: paymentInfo) { (result) in print("psphostSDK finished with status \(result.status.rawValue)") if let error = result.error { // в случае ошибки print("Error: \(error.localizedDescription)") } if let token = result.token { // при генерации токена print("Token: \(token)") } }
[self.psphostSDK presentPaymentAt:self paymentInfo:paymentInfo completionHandler:^(psphostPaymentResult *result) { NSLog(@"psphostSDK finished with status %ld", (long)result.status); if(result.error != NULL) { // в случае ошибки NSLog(@"Error: %@", result.error.localizedDescription); } if(result.token != NULL) { // при генерации токена NSLog(@"Token: %@", result.token); } }];
Код результата | Константа результата | Значение | Описание |
---|---|---|---|
0 | Success | Success | Платеж проведен |
100 | Decline | General decline | Платеж отклонен из-за получения общей ошибки от платежной платформы |
301 | Cancelled | Cancelled | Платеж отменен пользователем |
501 | Error | Internal error | Возникла внутренняя ошибка |
Обработка оповещений
Обзор
При работе с SDK для iOS поддерживается использование оповещений, отправляемых платежной платформой PSPHost напрямую к веб-сервису мерчанта, и оповещений, передаваемых вначале от платежной формы к SDK для iOS, а затем — от SDK для iOS к мобильному приложению мерчанта. В первом случае набор параметров, передаваемых в оповещении, может отличаться в зависимости от установленных настроек (подробнее: Как выглядит оповещение в PSPHost). Во втором случае передается строго определенный набор параметров — данные о статусе, типе и идентификаторе платежа, дате проведения платежа, используемом платежном методе, сумме и валюте платежа:
{
"payment": {
"status": "success",
"type": "purchase",
"id": "12345",
"date": "2020-09-11T14:49:18+0000",
"method": "card",
"sum": 1000,
"currency": "USD"
}
}
Далее представлена информация об этих оповещениях.
Оповещения платежной платформы
При проведении платежа платежная платформа отправляет оповещения на указанный URL. Этот URL необходимо сообщить службе технической поддержки PSPHost. Подробная информация об оповещениях представлена в разделе Оповещения (callbacks) в Payment Page.
Оповещения SDK для iOS
Мобильное приложение мерчанта может принимать от SDK для iOS оповещения, которые передаются к SDK для iOS от платежной платформы. Оповещение отправляется мерчанту до того, как пользователю в платежной форме отображается страница с информацией о результате проведения платежа.
Для получения оповещения с информацией о результате проведения платежа необходимо использовать публичный протокол PsphostCallback
. В рамках PsphostCallback
задействуется метод onPaymentResult, который выполняется автоматически при получении финального статуса платежа и при выполнении которого предоставляется информация о платеже. Для получения информации о результате проведения платежа можно использовать приведенные далее примеры и дополнительно ничего не настраивать; при необходимости также возможно изменение мерчантом данного кода.
class YourClass: PsphostCallback {
func presentPaymentPage() {
psphostSDK = PsphostSDK(callback: self)
...
}
func onPaymentResult(paymentData: PsphostPaymentData) {
// callback
}
}
@interface YourClass() <PsphostCallback> { PsphostSDK *psphostSDK; }
@implementation YourClass
...
- (void)presentPaymentPage {
self.psphostSDK = [[PsphostSDK alloc] callback: self];
...
}
- (void)onPaymentResult:(PsphostPaymentData *)paymentData {
// callback
}
Управление платежными данными
При оплате с помощью платежной карты пользователю необходимо ввести данные карты на платежной форме. Кроме традиционного способа ввода данных (вручную) SDK для iOS позволяет сканировать карту, использовать сохраненную карту или токен карты для оплаты.
Оплата с использованием сохраненных данных
Пользователь может сохранить реквизиты карты при совершении оплаты. Тогда при проведении последующих платежей пользователю достаточно лишь выбрать карту из списка сохраненных и ввести значение CVV.
Для обеспечения возможности сохранения данных карты и проведения оплаты по сохраненным данным пользователя в объект PaymentInfo
необходимо добавить параметр customerID, который позволяет привязать список карт к определенному пользователю на стороне платежной платформы. При проведении данного типа платежей SDK для iOS отправляет запрос в платежную платформу на получение списка сохраненных карт пользователя и при наличии таковых выводит их на платежной форме. Если пользователь исключает карту из списка сохраненных, то SDK для iOS отправляет запрос в платежную платформу на удаление данных из списка сохраненных платежных инструментов.
Оплата с использованием токенов
SDK для iOS предоставляет возможность проводить платежи по токену карты. В этом случае на стороне серверной части приложения необходимо обеспечить хранение данных карты пользователя и ее токена. Если заданный токен соответствует карте пользователя, то при проведении оплаты пользователю отображается форма оплаты с предварительно выбранной картой и заполненными данными этой карты, кроме CVV.
При использовании токена для проведения оплат параметр token должен быть включен в список параметров для подписывания.
Для оплаты по токену необходимо задать токен в объекте paymentInfo
:
paymentInfo.setToken(token);
[paymentInfo setToken:token];
Автоматическая генерация токена
"account": { "number": "546942******3838", "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b", "type": "mastercard", "card_holder": "JOHN SMITH", "id": 7279487, "expiry_month": "11", "expiry_year": "2021" },
Генерация токена по запросу
Tokenize
в типе действия:paymentInfo.setAction(action: .Tokenize)
[paymentInfo setAction:ActionTypeTokenize];
Сгенерированный токен и время его создания возвращаются в оповещении о генерации токена.
Проведение платежей
Базовый вариант оплаты
По умолчанию в SDK для iOS настроено проведение разовых одностадийных оплат (тип действия Sale
). Для проведения данного типа оплат можно использовать приведенные примеры и дополнительно ничего не настраивать.
Разовая двухстадийная оплата
- Задать значение
Auth
в типе действия.Рис. 19. Swift paymentInfo.setAction(action: .Auth)
Рис. 20. Objective-C [paymentInfo setAction:ActionTypeAuth];
- Подтвердить списание средств через Dashboard или с помощью запроса на /v2/payment/card/capture.
Подробная информация о проведении оплат с предварительной блокировкой представлена в разделе Блокировка средств.
Повторяемая оплата
sale
, auth
и verify
и поддерживается только для оплат с использованием платежных карт.- Создать объект
RecurrentInfo
с параметрами:- type — тип повторяемой оплаты (
.OneClick
,.Regular,
или.Autopayment
), - cardOperationType — тип операции, в рамках которой регистрируется повторяемая оплата. Возможные значения:
sale
— оплата с прямым списанием средств,auth
— предварительная блокировка средств при проведении двухстадийной оплаты,verify
— проверка действительности платежного инструмента.
- expiryDay — день окончания действия подписки,
- expiryMonth — месяц окончания действия подписки,
- expiryYear — год окончания действия подписки,
- period — периодичность проведения повторяемых оплат,
- time — время проведения повторяемых оплат,
- startDate — дата проведения первой повторяемой оплаты,
- scheduledPaymentID — идентификатор повторяемой оплаты в проекте.
Рис. 21. Swift let recurrentInfo = RecurrentInfo(type: .Regular, cardOperationType: "sale", expiryDay: "20", expiryMonth: "11", expiryYear: "2020", period: .Month, time: "12:00:00", startDate: "12-08-2019", scheduledPaymentID: "your_recurrent_id")
Рис. 22. Objective-C RecurrentInfo *recurrentInfo = [[RecurrentInfo alloc] initWithRecurrentType:RecurrentTypeAutopayment cardOperationType:@"sale" expiryDay:@"20" expiryMonth:@"11" expiryYear:@"2020" period:RecurrentPeriodMonth ntime:@"12:00:00" startDate:@"12-08-2020" scheduledPaymentID:@"your_recurrent_id"];
Дополнительно можно задать:
-
Сумму списания. По умолчанию сумма списания равна сумме платежа. Задать другую сумму списания можно в объекте
RecurrentInfo
:Рис. 23. Swift recurrentInfo.setAmount(amount: 1000)
Рис. 24. Objective-C [recurrentInfo setAmount:1000];
-
Дат и сумм списания. По умолчанию при повторяемых оплатах средства списываются с карты строго фиксированно по времени и сумме, но можно задать собственное расписание в объекте
recurrentInfo
:Рис. 25. Swift recurrentInfo.setSchedule(schedule: [ RecurrentInfoSchedule(date: "10-10-2020", amount: 1200), RecurrentInfoSchedule(date: "10-11-2020", amount: 1000), ... ])
Рис. 26. Objective-C [recurrentInfo setSchedule:@[ [[RecurrentInfoSchedule alloc] initWithDate:@"10-10-2020" amount:1200], [[RecurrentInfoSchedule alloc] initWithDate:@"10-11-2020" amount:1000], ... ]];
- type — тип повторяемой оплаты (
- Добавить объект
RecurrentInfo
в объектPaymentInfo
.Рис. 27. Swift paymentInfo.setRecurrent(recurrent: recurrentInfo)
Рис. 28. Objective-C [paymentInfo setRecurret:recurrentInfo];
Проверка действительности платежного инструмента
Проверка действительности платежного инструмента используется в случае необходимости проверки карты пользователя без списания средств, а также для сохранения данных карты с целью дальнейшего использования. При проверке карты выполняется списание с карты нулевой суммы.
Для проведения верификации карты необходимо задать Verify
в типе действия:
paymentInfo.setAction(action: .Verify)
[paymentInfo setAction:ActionTypeVerify];
Оплата с использованием альтернативных платежных методов
Общая информация
SDK для iOS поддерживает проведение оплат с использованием альтернативных платежных методов. Описание каждого из этих методов представлено в отдельной статье, а схемы проведения оплат через SDK для iOS с использованием этих методов можно разбить на два типа: с подтверждением в сервисе альтернативной платежной системы возможности проведения платежа (это актуально для Apple Pay) и с перенаправлением пользователя к сервису альтернативной платежной системы для подтверждения и обработки платежа (это актуально для остальных методов). Далее представлены обе схемы, а также описание особенностей работы с методом Apple Pay и поддерживаемыми сценариями оплат метода WebMoney.
Для подключения возможности проведения платежей с использованием альтернативных платежных методов следует обратиться к специалистам технической поддержки PSPHost.
Apple Pay
Чтобы обеспечить возможность проведения оплат с использованием метода Apple Pay, предварительно необходимо:
- Зарегистрировать в Apple идентификатор мерчанта (Merchant ID), позволяющий принимать платежи с использованием метода Apple Pay. Этот идентификатор действует бессрочно и может использоваться для разных сайтов и приложений iOS. Информация о регистрации этого идентификатора представлена в документации Apple: Create a merchant identifier.
- Выпустить сертификат обработки платежей (Payment Processing Certificate). Этот сертификат используется в связке с идентификатором мерчанта и позволяет обеспечивать безопасность платежных данных при проведении платежей с использованием метода Apple Pay. Информация о выпуске этого сертификата представлена в документации Apple: Create a payment processing certificate.
- Передать специалистам технической поддержки PSPHost сертификат обработки платежей, используя при этом оговоренные методы защиты.
- Включить поддержку Apple Pay для проекта мобильного приложения в используемой среде разработки. Информация об этой настройке для среды Xcode представлена в документации Apple: Enable Apple Pay.
После этого можно проводить оплаты с использованием Apple Pay. Все основные процедуры — вызов платежной формы, прием результатов и обработка оповещений — выполняются при этом так же, как и при работе с другими методами, а при формировании запросов необходимо учитывать следующее:
- Должен указываться идентификатор мерчанта (Merchant ID). Это можно сделать следующим образом:
Swift
paymentInfo.setApplePayMerchantID(merchantID: "merchant.example.com")
Objective-C
[paymentInfo setApplePayMerchantID:@"merchant.example.com"];
- Валютой платежа может быть EUR, GBP, RUB или USD.
- Для корректного формирования платежной сессии Apple Pay следует указывать код страны нахождения пользователя (в формате ISO 3166 alpha‑2) в параметре regionCode.
- В случае необходимости возможно добавление дополнительной информации о платеже на страницу авторизации платежа Apple Pay — с помощью параметра applePayDescription. Необходимую для добавления информацию следует передать в значении данного параметра; для корректного отображения информации значение параметра рекомендуется указывать кратко. Полученное значение отображается в поле Pay на странице авторизации платежа Apple Pay (поддерживается для режимов работы платежной формы
sale
,auth
иverify
). Передача параметра applePayDescription в запросе не является обязательной; если данный параметр не передан, в поле Pay на странице авторизации платежа Apple Pay отображается значение параметра paymentID.
Оплаты с использованием метода Apple Pay проводятся следующим образом.
- Пользователь инициирует оплату.
- От мобильного приложения к SDK для iOS передается запрос на открытие платежной формы.
- Запрос на открытие платежной формы передается к платежной платформе.
- В платежной платформе выполняется обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платежной платформы к SDK для iOS передается ответ на запрос.
- Пользователю отображается платежная форма, сконфигурированная с учетом особенностей проекта и параметров вызова.
- Пользователь выбирает для проведения оплаты метод Apple Pay.
- От SDK для iOS к сервису Apple Pay передается запрос на создание платежной сессии.
- На стороне Apple Pay выполняются обработка запроса и подготовка данных для создания платежной сессии.
- От сервиса Apple Pay к SDK для iOS передаются данные платежной сессии.
- Пользователю отображается форма аутентификации Apple Pay.
- Пользователь выполняет необходимые действия для подтверждения своей личности.
- По запросу от SDK для iOS на используемом пользовательском устройстве выполняется подтверждение личности пользователя.
- От SDK для iOS к платежной платформе передается запрос на проведение оплаты.
- На стороне платежной платформы выполняется обработка запроса.
- Запрос на оплату передается к сервису международной платежной системы.
- На стороне международной платежной системы выполняется обработка платежа.
- От международной платежной системы к платежной платформе передается информация о результате проведения оплаты.
- От платежной платформы к серверной части мобильного приложения передается оповещение о результате проведения оплаты.
- От платежной платформы к SDK для iOS передается информация о результате проведения оплаты.
- Информация о результате оплаты отображается пользователю в платежной форме.
Также поддерживается регистрация повторяемых оплат с использованием платежного метода Apple Pay. Подробная информация о необходимых параметрах и примеры пода на языках программирования Swift и Objective-C представлены в разделе Повторяемая оплата.
WebMoney
При работе с SDK для iOS поддерживается проведение оплат с использованием сценариев WebMoneyLight и WebMoneyClassic. При использовании WebMoneyLight осуществляется перенаправление пользователя к форме оплаты WebMoney для перевода средств на WM-кошелек мерчанта. При использовании WebMoneyClassic пользователь самостоятельно переходит в сервис WebMoney для проведения оплаты. Все основные процедуры, такие как вызов платежной формы, прием результатов и обработка оповещений, выполняются так же, как и при работе с другими платежными методами, а при формировании запросов необходимо учитывать следующее:
- Для сценария оплаты WebMoneyClassic поддерживается возможность автоматического инициирования оплаты без указания пользователем данных в платежной форме. Для этого, помимо базового минимального набора параметров (подробнее: Вызов платежной формы), мерчанту необходимо передать в запросе на открытие платежной формы значения обоих следующих параметров:
- accountNumber — идентификатор пользователя в сервисе WebMoney (WMID).
- accountPurseType — тип кошелька WebMoney.
Если в запросе переданы значения обоих указанных параметров, проведение оплаты инициируется автоматически без возможности для пользователя изменить указанные данные.
Если в запросе передано значение только одного из указанных параметров, в платежной форме пользователю отображается поле для ввода запрашиваемых данных. В этом случае проведение оплаты начинается после указания пользователем необходимых данных.
Другие методы
Оплаты с перенаправлением к сервисам альтернативных платежных систем проводятся следующим образом.
Сбор данных о пользователе
Для проведения платежа с использованием платежной формы обычно требуется минимальный набор параметров, при этом для сбора данных о пользователях можно передавать и (или) запрашивать дополнительные данные, например, телефон или электронную почту пользователя. Подробнее — Сбор данных о пользователе.
paymentInfo
необходимо задать список дополнительных параметров и их значение:paymentInfo.setAdditionalFields(additionalFields: [ AdditionalField(type: .customer_first_name, value: "Mark"), AdditionalField(type: .billing_country, value: "US"), AdditionalField.init(type: .aps_account_number, value: ""), AdditionalField.init(type: .aps_account_security_code, value: "") .... ])
[paymentInfo setAdditionalFields:@[ [[AdditionalField alloc] initWithType:customer_first_name value:@"Mark"], [[AdditionalField alloc] initWithType:billing_country value:@"US"], [[AdditionalField alloc] initWithType:aps_account_number value: ""], [[AdditionalField alloc] initWithType:aps_account_security_code value: ""] ... ]];
Индивидуальный дизайн
- использовать светлую или темную тему,
Рис. 35. Светлая тема платежной формы Рис. 36. Темная тема платежной формы - настраивать оформление отдельных элементов,
Использование темы
let theme = PsphostTheme.getDarkTheme() psphostSDK.setTheme(theme: theme)
PsphostTheme *theme = [PsphostTheme getDarkTheme]; [self.psphostSDK setTheme:theme];
Настройка оформления отдельных элементов
theme.backgroundColor = UIColor.green theme.showDarkKeyboard = true
theme.backgroundColor = UIColor.greenColor; theme.showDarkKeyboard = true;
overlayColor
— цвет затемнения открытой области платежной формы,backgroundColor
— цвет фона платежной формы,headingTextColor
— цвет текста заголовка,menuTextColor
— цвет текста кнопок в заголовке модального окна,fieldTextColor
— цвет текста дополнительных полей, названий платежных методов, данных на странице с информацией о результате проведения платежа,supportiveTextColor
— цвет вспомогательного текста,fieldPlaceholderTextColor
— цвет заполнителей полей,fieldImageTintColor
— цвет иконок в полях ввода при оплате новой картой и в поле CVV,fieldTextCorrectColor
— цвет текста при успешной проверке заполнения полей,fieldTextWrongColor
— цвет текста при неуспешной проверке заполнения полей,fieldBackgroundColor
— цвет кнопок платежных систем и поля CVV,primaryTintColor
— основной цвет кнопок и иконок платежной формы,secondaryTintColor
— вспомогательный цвет платежной формы,lineColor
— цвет линий полей на странице оплаты новой картой,actionButtonDisableBackgroundColor
— цвет заблокированной кнопки,actionButtonDisableTextColor
— цвет текста на заблокированной кнопке,actionButtonTextColor
— цвет текста на активной кнопке,showShadow
— включение тени кнопок платежных методов и сохраненных карт на странице выбора платежных методов,showDarkKeyboard
— использование темной темы клавиатуры,showDarkNavigationBar
— использование темной темы панели навигации,showLightLogo
— включение светлых логотипов при использовании темной темы.