SDK для iOS (legacy)

Возможности

Также поддерживается проведение платежей с использованием методов, информация о которых представлена в разделе Методы. По вопросам, связанным с подключением этих платёжных методов, следует обращаться к курирующему менеджеру ecommpay.

Состав

SDK для iOS содержит библиотеку, которая задействуется при разработке и использовании приложений на устройствах Apple, и примеры работы на языках программирования Swift и Objective-C.

Схема работы

Рис.: Схема взаимодействия

Подключение и использование

При возникновении вопросов о работе с SDK для iOS следует обращаться в службу технической поддержки ecommpay support@ecommpay.com.

Интерфейс платёжной формы

Рис.: Отображение списка доступных платёжных методов

Рис.: Оплата с использованием альтернативного платёжного метода DOKU

Рис.: Проверка действительности карты

Рис.: Выбор сохранённой карты

Рис.: Генерация токена карты

Рис.: Использование предварительно выбранной карты

Рис.: Уточнение дополнительных параметров, обязательных для проведения оплаты

Рис.: Возможность повторных попыток оплаты в случае ошибок

Подключение в Swift

Подключение в Objective-C

Для подключения библиотек к проекту мобильного приложения необходимо:

1. Перенести файл ecommpaySDK.xcframework в папку проекта мобильного приложения.
2. Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо:
   1. Открыть цель (target) проекта.
   2. Перейти в General > Embedded Binaries.
   3. Щёлкнуть +.
   4. Щёлкнуть Add Other.
   5. Выбрать файл ecommpaySDK.xcframework.
   6. Щёлкнуть Add.
   7. Выбрать раздел Build Settings.
   8. Установить переключатель Always embed swift embedded libraries в положение Yes.
3. Добавить ключ NSCameraUsageDescription со значением permission is needed in order to scan card в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через её сканирование.

4. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

   ecommpay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.

   Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.

5. Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ Privacy - Photo Library Usage Description и ключ Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных.

Подключение библиотеки через CocoaPods

Для подключения библиотек через CocoaPods необходимо:

1. Открыть файл Podfile и добавить в него строки:

   target 'App' do
     # Pods for App
     pod 'Paymentpage-sdk-ios', '1.10.0'
   end

2. Добавить ключ NSCameraUsageDescription со значением permission is needed in order to scan card в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через её сканирование.

3. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

   ecommpay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.

   Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.

4. Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ Privacy - Photo Library Usage Description и ключ Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных.

Вызов в Swift

Для вызова платёжной формы необходимо выполнить следующие действия:

Вызов в Objective-C

Для вызова платёжной формы необходимо выполнить следующие действия:

Обзор

При работе с SDK для iOS поддерживается использование оповещений, отправляемых платёжной платформой ecommpay напрямую к веб-сервису мерчанта, и оповещений, передаваемых вначале от платёжной формы к SDK для iOS, а затем — от SDK для iOS к мобильному приложению мерчанта. В первом случае набор параметров, передаваемых в оповещении, может отличаться в зависимости от установленных настроек (подробнее: Оповещения). Во втором случае передаётся строго определённый набор параметров — данные о статусе, типе и идентификаторе платежа, дате проведения платежа, используемом платёжном методе, сумме и валюте платежа:

{
    "payment": {
        "status": "success",
        "type": "purchase",
        "id": "12345",
        "date": "2020-09-11T14:49:18+0000",
        "method": "card",
        "sum": 1000,
        "currency": "USD"
         }
}

Далее представлена информация об этих оповещениях.

Оповещения платёжной платформы

При проведении платежа платёжная платформа отправляет оповещения на указанный URL. Этот URL необходимо сообщить службе технической поддержки ecommpay. Подробная информация об оповещениях представлена в разделе Оповещения.

Оповещения SDK для iOS

Мобильное приложение мерчанта может принимать от SDK для iOS оповещения, которые передаются к SDK для iOS от платёжной платформы. Оповещение отправляется мерчанту до того, как пользователю в платёжной форме отображается страница с информацией о результате проведения платежа.

Для получения оповещения с информацией о результате проведения платежа необходимо использовать публичный протокол ECMPCallback. В рамках ECMPCallback задействуется метод onPaymentResult, который выполняется автоматически при получении финального статуса платежа и при выполнении которого предоставляется информация о платеже. Для получения информации о результате проведения платежа можно использовать приведённые далее примеры и дополнительно ничего не настраивать; при необходимости также возможно изменение мерчантом данного кода.

class YourClass: ECMPCallback {
    func presentPaymentPage() {
        ecommpaySDK = EcommpaySDK(callback: self)
        ...
    }
 
    func onPaymentResult(paymentData: ECMPPaymentData) {
        // callback
    }
}

@interface YourClass() <ECMPCallback> { EcommpaySDK *ecommpaySDK; }
 
@implementation YourClass
 
...
 
- (void)presentPaymentPage {
    self.ecommpaySDK = [[EcommpaySDK alloc] callback: self];
    ...
}
 
- (void)onPaymentResult:(ECMPPaymentData *)paymentData {
    // callback
}

Оплата с использованием сохранённых данных

Пользователь может сохранить реквизиты карты при совершении оплаты. Тогда при проведении последующих платежей пользователю достаточно лишь выбрать карту из списка сохранённых и ввести значение CVV.

Для обеспечения возможности сохранения данных карты и проведения оплаты по сохранённым данным пользователя в объект PaymentInfo необходимо добавить параметр customerID, который позволяет привязать список карт к определённому пользователю на стороне платёжной платформы. При проведении данного типа платежей SDK для iOS отправляет запрос в платёжную платформу на получение списка сохранённых карт пользователя и при наличии таковых выводит их на платёжной форме. Если пользователь исключает карту из списка сохранённых, то SDK для iOS отправляет запрос в платёжную платформу на удаление данных из списка сохранённых платёжных инструментов.

Оплата с использованием токенов

SDK для iOS предоставляет возможность проводить платежи по токену карты. В этом случае на стороне серверной части приложения необходимо обеспечить хранение данных карты пользователя и её токена. Если заданный токен соответствует карте пользователя, то при проведении оплаты пользователю отображается форма оплаты с предварительно выбранной картой и заполненными данными этой карты, кроме CVV.

При использовании токена для проведения оплат параметр token должен быть включён в список параметров для подписывания.

Для оплаты по токену необходимо задать токен в объекте paymentInfo:

paymentInfo.setToken(token);

[paymentInfo setToken:token];

Автоматическая генерация токена

"account": {
            "number": "541333****0019",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

Генерация токена по запросу

paymentInfo.setAction(action: .Tokenize)

[paymentInfo setAction:ActionTypeTokenize];

Сгенерированный токен и время его создания возвращаются в оповещении о генерации токена.

Базовый вариант оплаты

По умолчанию в SDK для iOS настроено проведение разовых одностадийных оплат (тип действия Sale). Для проведения данного типа оплат можно использовать приведённые примеры и дополнительно ничего не настраивать.

Разовая двухстадийная оплата

Подробная информация о проведении оплат с предварительной блокировкой представлена в разделе Блокировка средств.

Повторяемая оплата

Проверка действительности платёжного инструмента

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

Для проведения верификации карты необходимо задать Verify в типе действия:

paymentInfo.setAction(action: .Verify)

[paymentInfo setAction:ActionTypeVerify];

Оплата с использованием альтернативных платёжных методов

Общая информация

SDK для iOS поддерживает проведение оплат с использованием альтернативных платёжных методов Apple Pay, Skrill Wallet, DOKU Wallet, Malaysian Online Banking, Thai Online Banking, Alipay, Neteller, а также оплат с использованием интернет-банкинга в странах Европы. Описание каждого из этих методов представлено в отдельной статье, а схемы проведения оплат через SDK для iOS с использованием этих методов можно разбить на два типа: с подтверждением в сервисе альтернативной платёжной системы возможности проведения платежа (это актуально для Apple Pay) и с перенаправлением пользователя к сервису альтернативной платёжной системы для подтверждения и обработки платежа (это актуально для остальных методов). Далее представлены обе схемы, а также описание особенностей работы с методом Apple Pay.

Для подключения возможности проведения платежей с использованием альтернативных платёжных методов следует обратиться к специалистам технической поддержки ecommpay.

Apple Pay

Чтобы обеспечить возможность проведения оплат с использованием метода Apple Pay, предварительно необходимо:

1. Зарегистрировать в Apple идентификатор мерчанта (Merchant ID), позволяющий принимать платежи с использованием метода Apple Pay. Этот идентификатор действует бессрочно и может использоваться для разных сайтов и приложений iOS. Информация о регистрации этого идентификатора представлена в документации Apple: Create a merchant identifier.
2. Выпустить сертификат обработки платежей (Payment Processing Certificate). Этот сертификат используется в связке с идентификатором мерчанта и позволяет обеспечивать безопасность платёжных данных при проведении платежей с использованием метода Apple Pay. Информация о выпуске этого сертификата представлена в документации Apple: Create a payment processing certificate.
3. Передать специалистам технической поддержки ecommpay сертификат обработки платежей, используя при этом оговорённые методы защиты.
4. Включить поддержку 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 или USD.
• Для корректного формирования платёжной сессии Apple Pay следует указывать код страны нахождения пользователя (в формате ISO 3166 alpha‑2) в параметре regionCode.
• В случае необходимости возможно добавление дополнительной информации о платеже на страницу авторизации платежа Apple Pay — с помощью параметра applePayDescription. Необходимую для добавления информацию следует передать в значении данного параметра; для корректного отображения информации значение параметра рекомендуется указывать кратко. Полученное значение отображается в поле Pay на странице авторизации платежа Apple Pay (поддерживается для режимов работы платёжной формы sale, auth и verify). Передача параметра applePayDescription в запросе не является обязательной; если данный параметр не передан, в поле Pay на странице авторизации платежа Apple Pay отображается значение параметра paymentID.

Оплаты с использованием метода Apple Pay проводятся следующим образом.

Также поддерживается регистрация повторяемых оплат с использованием платёжного метода Apple Pay. Подробная информация о необходимых параметрах и примеры пода на языках программирования Swift и Objective-C представлены в разделе Повторяемая оплата.

Другие методы

Оплаты с перенаправлением к сервисам альтернативных платёжных систем проводятся следующим образом.

Рис.: Проведение оплаты с использованием альтернативных платёжных методов (АПМ)