SDK для iOS (legacy)

SDK для iOS — это набор средств разработки для подключения мобильных приложений, работающих на платформе iOS, к платёжной платформе ecommpay. В этом разделе представлена информация о работе с 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.

Прим.: SDK для iOS в конфигурации, описанной в этой статье, остаются в поддержке, но уже без дальнейшего функционального развития. Вместо них предпочтительнее использовать новые поколения SDK для мобильных приложений.
Для SDK для iOS поддерживается подключение библиотек через CocoaPods (подробнее). Также SDK для iOS можно загрузить с GitHub по следующим ссылкам:

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

Возможности

SDK для iOS позволяет проводить платежи с использованием платёжных карт, а также альтернативных платёжных методов. Для платежей с использованием карт доступны проведение разовых и повторяемых оплат, проверка действительности карт (подробнее). Среди поддерживаемых альтернативных платёжных методов доступны следующие:

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

При работе с SDK для iOS используется платёжная форма ecommpay, в рамках работы с которой доступны следующие возможности:
  • Поддержка русского, английского, испанского, итальянского, немецкого и французского языков. Платёжная форма может отображаться на языке интерфейса мобильного устройства пользователя или на том языке, который для платёжной формы указывается со стороны мерчанта. При этом необходимо учитывать следующее:
    • Если со стороны мерчанта указывается поддерживаемый SDK для iOS язык, платёжная форма отображается на указанном языке.
    • Если со стороны мерчанта указывается не поддерживаемый SDK для iOS язык, платёжная форма отображается на английском языке.
    • Если со стороны мерчанта язык не указывается, платёжная форма отображается на языке интерфейса мобильного устройства, если этот язык поддерживается SDK для iOS, или на английском языке, если язык интерфейса мобильного устройства не поддерживается SDK для iOS.
  • Поддержка индивидуального дизайна и настройка цветового оформления платёжной формы (подробнее).
  • Поддержка разных способов ввода данных карты (подробнее):
    • вручную,
    • сканируя карту,
    • выбирая сохранённую карту,
    • используя предварительно выбранную карту.
  • Сбор или указание дополнительных данных о пользователе (подробнее).
  • Уточнение дополнительных параметров, обязательных для проведения оплаты (подробнее).
  • Поддержка аутентификации 3‑D Secure 2. Протокол 3‑D Secure 2 является новой версией протокола 3‑D Secure (Three-Domain Secure), который обеспечивает безопасное проведение интернет-оплат с использованием платёжных карт (подробнее).
  • Поддержка повторных попыток оплаты в случае ошибок (подробнее).
  • Получение информации о платеже: на всех страницах платёжной формы доступна кнопка информации, при выборе которой отображаются данные о сумме, идентификаторе и дате проведения платежа, а также описание платежа.
  • Отправка электронного товарного чека пользователю (подробнее).

Состав

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

Схема работы

Проведение платежей с использованием SDK для iOS выполняется следующим образом:
  1. В клиентской части мобильного приложения формируется объект с необходимыми параметрами для проведения платежа.
  2. В серверной части мобильного приложения вычисляется подпись на основании параметров платежа.
  3. В клиентской части формируется итоговый запрос на проведение платежа и с помощью библиотеки отправляется в платёжную платформу ecommpay.
  4. В платёжной платформе выполняется обработка платежа.
  5. От платёжной платформы к клиентской части отправляется результат выполнения платежа.
  6. От платёжной платформы на заданный URL отправляется оповещение.
Рис. 1. Схема взаимодействия


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

Для использования SDK для iOS необходимо:
  1. Решить организационные вопросы, касающиеся взаимодействия с ecommpay:
    • Если у компании нет идентификатора и ключа для взаимодействия с ecommpay — отправить заявку на подключение.
    • Если у компании есть идентификатор и ключ для взаимодействия с ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для iOS и согласовать с ними порядок тестирования и запуска.
  2. Выполнить подготовительные технические работы:
    1. Обеспечить подписывание данных на стороне серверной части мобильного приложения.
    2. Скачать библиотеку SDK для iOS.
    3. Подключить библиотеку к клиентской части мобильного приложения.
    4. Доработать клиентскую часть мобильного приложения для инициирования платежей необходимых типов и обработки результатов этих платежей.
  3. Протестировать и запустить в работу обновлённое приложение.
    1. Для тестирования следует использовать тестовый идентификатор проекта и данные тестовых карт, предоставленные специалистами технической поддержки ecommpay.
    2. Для перевода в рабочий режим следует изменить тестовое значение идентификатора проекта на рабочее значение, полученное от ecommpay.

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

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

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


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


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


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


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


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


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


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


Обеспечение работы с подписью

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

Рис. 10. Процесс подписывания данных


Получив строку для подписывания, необходимо выполнить следующие действия:
  1. Вычислить код HMAC для полученной строки на основе алгоритма SHA-512 и секретного ключа.
  2. Выполнить кодировку результата по алгоритму Base64.
Для проверки результата подписывания в серверной части приложения можно использовать следующий пример:
  • Строка для подписывания.
    customer_id:5;payment_amount:30;payment_currency:EUR;payment_id:payment1;project_id:115
  • Значение секретного ключа — 12345.
  • Результат генерации подписи.
    pVmAtGFBQJD2NgLToP1B2elR4QROiYGi3IobPD9PFDfrkjBqdSCFgrVSEtebVJUzOUUHX5tPnHQq9RMn61679A==

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

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

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

Для подключения библиотек к проекту мобильного приложения необходимо:
  1. Перенести файл ecommpaySDK.xcframework в папку проекта мобильного приложения.
  2. Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо:
    1. Открыть цель (target) проекта.
    2. Перейти в General > Embedded Binaries.
    3. Щёлкнуть +.
    4. Щёлкнуть Add Other.
    5. Выбрать файл ecommpaySDK.xcframework.
    6. Щёлкнуть Add.
  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. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных.

Подключение в 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

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

  1. Импортировать библиотеку.
    import ecommpaySDK
  2. Объявить библиотеку ecommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
    let ecommpaySDK = EcommpaySDK()
  3. Создать объект PaymentInfo. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
    • projectID — идентификатор проекта, полученный от ecommpay при интеграции;
    • paymentID — идентификатор платежа, уникальный в рамках проекта;
    • paymentAmount — сумма платежа в дробных единицах;
    • paymentCurrency — валюта платежа в формате ISO-4217 alpha-3;
    • для оплат с прямым использованием платёжных карт — customerEmail или customerPhone (по крайней мере один из этих параметров).

    Пример объекта PaymentInfo, который содержит только обязательные параметры:

    let paymentInfo = PaymentInfo(projectID: 10,
                        paymentID: "internal_payment_id_1",
                        paymentAmount: 1999,
                        paymentCurrency: "USD")
    Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Для таких случаев становится обязательным передавать по крайней мере один из следующих параметров: customerEmail или customerPhone. Эти параметры также необходимо указывать в объекте PaymentInfo.

    Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения. К параметрам с информацией о платёжном адресе пользователя относятся код страны в формате ISO 3166-1 alpha-2 (billingCountry), индекс (billingPostal), название города (billingCity) и название улицы (billingAddress).

    Дополнительно могут использоваться следующие объекты и параметры:
    • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
    • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
    • customerID — идентификатор пользователя, уникальный в рамках проекта.
    • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
    • token — токен карты.
    • action — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
    • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды платёжных методов.
    • hideSavedWallets — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости скрывать сохранённые платёжные инструменты в платёжной форме. Возможные значения:
      • true — сохранённые ранее платёжные инструменты скрыты, они не отображаются при открытии платёжной формы.
      • false — сохранённые ранее платёжные инструменты отображаются при открытии платёжной формы.
    • ECMPScreenDisplayMode — объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать её. В объекте необходимо передавать следующие параметры:
      • hide_success_final_page — финальная страница с сообщением о совершённом платеже не отображается в платёжной форме,
      • hide_decline_final_page — финальная страница с сообщением об отклонённом платеже не отображается в платёжной форме.

      Пример передачи в запросе параметров hide_success_final_page и hide_decline_final_page:

      // Init ECMPPaymentInfo
 
paymentInfo.addEcmpScreenDisplayMode(value: "hide_success_final_page")
           .addEcmpScreenDisplayMode(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")
  4. Получить строку для подписывания указанных параметров.
    paymentInfo.getParamsForSignature();
  5. Передать сгенерированную строку в серверную часть приложения.
  6. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть.
  7. Добавить подпись в объект PaymentInfo.
    paymentInfo.setSignature(value: signature)
  8. Вызвать платёжную форму.
    ecommpaySDK.presentPayment(at: self, paymentInfo: paymentInfo) { (result) in
   print("ecommpay SDK 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

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

  1. Импортировать библиотеку.
    #import <ecommpaySDK/ECommPayhostsSDK.h>
  2. Объявить библиотеку EcommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
    EcommpaySDK *ecommpaySDK = [[EcommpaySDK alloc] init];
  3. Создать объект PaymentInfo. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
    • projectID — идентификатор проекта, полученный от ecommpay при интеграции;
    • paymentID — идентификатор платежа, уникальный в рамках проекта;
    • paymentAmount — сумма платежа в дробных единицах;
    • paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.
    Пример объекта PaymentInfo, который содержит только обязательные параметры:
    PaymentInfo *paymentInfo = [[PaymentInfo alloc] initWithProjectID:10
                        paymentID:@"internal_payment_id_1"
                        paymentAmount:1999
                        paymentCurrency:@"USD"];
    Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Для таких случаев становится обязательным передавать по крайней мере один из следующих параметров: customerEmail или customerPhone. Эти параметры также необходимо указывать в объекте PaymentInfo.

    Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения. К параметрам с информацией о платёжном адресе пользователя относятся код страны в формате ISO 3166-1 alpha-2 (billingCountry), индекс (billingPostal), название города (billingCity) и название улицы (billingAddress).

    Дополнительно могут использоваться следующие объекты и параметры:
    • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
    • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
    • customerID — идентификатор пользователя, уникальный в рамках проекта.
    • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
    • token — токен карты.
    • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
    • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды платёжных методов.
    • hideSavedWallets — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости скрывать сохранённые платёжные инструменты в платёжной форме. Возможные значения:
      • true — сохранённые ранее платёжные инструменты скрыты, они не отображаются при открытии платёжной формы.
      • false — сохранённые ранее платёжные инструменты отображаются при открытии платёжной формы.
    • ECMPScreenDisplayMode — объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать её. В объекте возможно передавать следующие параметры:
      • hide_success_final_page — финальная страница с сообщением о совершённом платеже не отображается в платёжной форме,
      • hide_decline_final_page — финальная страница с сообщением об отклонённом платеже не отображается в платёжной форме.

      Пример передачи в запросе параметров hide_success_final_page и hide_decline_final_page:

      // Init ECMPPaymentInfo
 
[paymentInfo addEcmpScreenDisplayMode: hide_success_final_page];
[paymentInfo addEcmpScreenDisplayMode: 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"];
  4. Получить строку для подписывания указанных параметров.
    paymentInfo.getParamsForSignature();
  5. Передать сгенерированную строку в серверную часть приложения.
  6. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть.
  7. Добавить подпись в объект PaymentInfo.
    [paymentInfo setSignature:signature];
  8. Вызвать платёжную форму.
    [self.ecommpaySDK presentPaymentAt:self paymentInfo:paymentInfo 
     completionHandler:^(ECPPaymentResult *result) {
     NSLog(@"ecommpaySDK finished with status %ld", (long)result.status);
     if(result.error != NULL) {                                  // в случае ошибки
         NSLog(@"Error: %@", result.error.localizedDescription);
     }
     if(result.token != NULL) {                               // при генерации токена
         NSLog(@"Token: %@", result.token);
     }
 }];

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

Приём результатов

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

Рис. 11. Приём результатов в Swift
ecommpaySDK.presentPayment(at: self, paymentInfo: paymentInfo) { (result) in
   print("ecommpaySDK finished with status \(result.status.rawValue)")
   if let error = result.error {                     // в случае ошибки
      print("Error: \(error.localizedDescription)")
   }
   if let token = result.token {                    // при генерации токена
      print("Token: \(token)")
   }
 }
Рис. 12. Приём результатов в Objective-C
[self.ecommpaySDK presentPaymentAt:self paymentInfo:paymentInfo 
     completionHandler:^(ECPPaymentResult *result) {
     NSLog(@"ecommpaySDK finished with status %ld", (long)result.status);
     if(result.error != NULL) {                                  // в случае ошибки
         NSLog(@"Error: %@", result.error.localizedDescription);
     }
     if(result.token != NULL) {                               // при генерации токена
         NSLog(@"Token: %@", result.token);
     }
 }];
Табл. 1. Допустимые коды ответов
Код результата Константа результата Значение Описание
0 Success Success Платёж проведён
100 Decline General decline Проведение платежа отклонено из-за получения общей ошибки от платёжной платформы
301 Cancelled Cancelled Проведение платежа отменено пользователем
501 Error Internal error Возникла внутренняя ошибка

Обработка оповещений

Обзор

При работе с 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, который выполняется автоматически при получении финального статуса платежа и при выполнении которого предоставляется информация о платеже. Для получения информации о результате проведения платежа можно использовать приведённые далее примеры и дополнительно ничего не настраивать; при необходимости также возможно изменение мерчантом данного кода.

Рис. 13. Swift
class YourClass: ECMPCallback {
    func presentPaymentPage() {
        ecommpaySDK = EcommpaySDK(callback: self)
        ...
    }
 
    func onPaymentResult(paymentData: ECMPPaymentData) {
        // callback
    }
}
Рис. 14. Objective-C
@interface YourClass() <ECMPCallback> { EcommpaySDK *ecommpaySDK; }
 
@implementation YourClass
 
...
 
- (void)presentPaymentPage {
    self.ecommpaySDK = [[EcommpaySDK alloc] callback: self];
    ...
}
 
- (void)onPaymentResult:(ECMPPaymentData *)paymentData {
    // callback
}

Управление платёжными данными

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

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

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

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

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

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

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

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

Рис. 15. Swift
paymentInfo.setToken(token);
Рис. 16. Objective-C
[paymentInfo setToken:token];

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

Автоматическая генерация токена происходит при проведении первой успешной оплаты по карте, а также при успешной блокировке средств. Сгенерированный токен и время его создания возвращаются в оповещении о проведении платежа.
Рис. 17. Фрагмент оповещения с токеном
"account": {
            "number": "541333****0019",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

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

Другим способом генерации токена является отправка запроса на генерацию токена. Для генерации токена необходимо задать Tokenize в типе действия:
Рис. 18. Swift
paymentInfo.setAction(action: .Tokenize)
Рис. 19. Objective-C
[paymentInfo setAction:ActionTypeTokenize];

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

Проведение платежей

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

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

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

Для проведения разовых двухстадийных оплат необходимо:
  1. Задать значение Auth в типе действия.
    Рис. 20. Swift
    paymentInfo.setAction(action: .Auth)
    Рис. 21. Objective-C
    [paymentInfo setAction:ActionTypeAuth];
  2. Подтвердить списание средств через Dashboard или с помощью запроса на /v2/payment/card/capture.

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

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

SDK для iOS поддерживает проведение повторяемых оплат. Такие оплаты бывают трёх типов: OneClick, автооплаты и регулярные оплаты. Подробнее о повторяемых оплатах — в разделе Общая информация.
Прим.: Регистрация повторяемых оплат при использовании SDK для iOS выполняется в рамках операций sale, auth и verify и поддерживается только для оплат с использованием платёжных карт.
Для проведения повторяемой оплаты необходимо:
  1. Создать объект RecurrentInfo с параметрами:
    • type — тип повторяемой оплаты (.OneClick, .Regular, или .Autopayment),
    • expiryDay — день окончания действия подписки,
    • expiryMonth — месяц окончания действия подписки,
    • expiryYear — год окончания действия подписки,
    • period — периодичность проведения повторяемых оплат,
    • time — время проведения повторяемых оплат,
    • startDate — дата проведения первой повторяемой оплаты,
    • scheduledPaymentID — идентификатор повторяемой оплаты в проекте.
    Рис. 22. Swift
    let recurrentInfo = RecurrentInfo(type: .Regular,
                    expiryDay: "20",
                    expiryMonth: "11",
                    expiryYear: "2030",
                    period: .Month,
                    time: "12:00:00",
                    startDate: "12-08-2021",
                    scheduledPaymentID: "your_recurrent_id")
    Рис. 23. Objective-C
    RecurrentInfo *recurrentInfo = [[RecurrentInfo alloc] 
                        initWithRecurrentType:RecurrentTypeAutopayment
                                                 expiryDay:@"20"
                                               expiryMonth:@"11"
                                                expiryYear:@"2030"
                                                    period:RecurrentPeriodMonth
                                                     time:@"12:00:00"
                                                 startDate:@"12-08-2021"
                                        scheduledPaymentID:@"your_recurrent_id"];

    Дополнительно можно задать:

    • Сумму списания. По умолчанию сумма списания равна сумме платежа. Задать другую сумму списания можно в объекте RecurrentInfo:
      Рис. 24. Swift
      recurrentInfo.setAmount(amount: 1000)
      Рис. 25. Objective-C
      [recurrentInfo setAmount:1000];
    • Дату и сумму списания. По умолчанию при повторяемых оплатах средства списываются с карты строго фиксированно по времени и сумме, но можно задать собственное расписание в объекте recurrentInfo:
      Рис. 26. Swift
      recurrentInfo.setSchedule(schedule: [
           RecurrentInfoSchedule(date: "10-10-2021", amount: 1200),
           RecurrentInfoSchedule(date: "10-11-2021", amount: 1000),
           ...
])
      Рис. 27. Objective-C
      [recurrentInfo setSchedule:@[
              [[RecurrentInfoSchedule alloc] initWithDate:@"10-10-2021" amount:1200],
              [[RecurrentInfoSchedule alloc] initWithDate:@"10-11-2021" amount:1000],
              ...
]];
  2. Добавить объект RecurrentInfo в объект PaymentInfo.
    Рис. 28. Swift
    paymentInfo.setRecurrent(recurrent: recurrentInfo)
    Рис. 29. Objective-C
    [paymentInfo setRecurret:recurrentInfo];

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

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

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

Рис. 30. Swift
paymentInfo.setAction(action: .Verify)
Рис. 31. Objective-C
[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 проводятся следующим образом.

Рис. 32. Проведение оплаты с использованием Apple Pay
  1. Пользователь инициирует оплату.
  2. От мобильного приложения к SDK для iOS передаётся запрос на открытие платёжной формы.
  3. Запрос на открытие платёжной формы передаётся к платёжной платформе.
  4. В платёжной платформе выполняется обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к SDK для iOS передаётся ответ на запрос.
  6. Пользователю отображается платёжная форма, сконфигурированная с учётом особенностей проекта и параметров вызова.
  7. Пользователь выбирает для проведения оплаты метод Apple Pay.
  8. От SDK для iOS к сервису Apple Pay передаётся запрос на создание платёжной сессии.
  9. На стороне Apple Pay выполняются обработка запроса и подготовка данных для создания платёжной сессии.
  10. От сервиса Apple Pay к SDK для iOS передаются данные платёжной сессии.
  11. Пользователю отображается форма аутентификации Apple Pay.
  12. Пользователь выполняет необходимые действия для подтверждения своей личности.
  13. По запросу от SDK для iOS на используемом пользовательском устройстве выполняется подтверждение личности пользователя.
  14. От SDK для iOS к платёжной платформе передаётся запрос на проведение оплаты.
  15. На стороне платёжной платформы выполняется обработка запроса.
  16. Запрос на оплату передаётся к сервису международной платёжной системы.
  17. На стороне международной платёжной системы выполняется обработка платежа.
  18. От международной платёжной системы к платёжной платформе передаётся информация о результате проведения оплаты.
  19. От платёжной платформы к серверной части мобильного приложения передаётся оповещение о результате проведения оплаты.
  20. От платёжной платформы к SDK для iOS передаётся информация о результате проведения оплаты.
  21. Информация о результате оплаты отображается пользователю в платёжной форме.

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

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

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

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

Сбор данных о пользователе

Для проведения платежа с использованием платёжной формы обычно требуется минимальный набор параметров, при этом для сбора данных о пользователях можно передавать и (или) запрашивать дополнительные данные, например, телефон или электронную почту пользователя. Подробнее — Сбор данных о пользователях.

Для передачи дополнительных данных о пользователе в объекте paymentInfo необходимо задать список дополнительных параметров и их значение:
Рис. 34. Swift
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: "")
          ....
])
Рис. 35. Objective-C
[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: ""]
                 ...
]];

Индивидуальный дизайн

Дизайн платёжной формы SDK для iOS можно менять:
  • использовать светлую или тёмную тему,
    Рис. 36. Светлая тема платёжной формы


    Рис. 37. Тёмная тема платёжной формы


  • настраивать оформление отдельных элементов,

Использование темы

SDK для iOS позволяет использовать две темы платёжной формы: светлую (по умолчанию) и тёмную. Для смены темы необходимо установить:
Рис. 38. Swift
let theme = ECPTheme.getDarkTheme()
ecompaySDK.setTheme(theme: theme)
Рис. 39. Objective-C
ECPTheme *theme = [ECPTheme getDarkTheme];
[self.ecommpaySDK setTheme:theme];

Настройка оформления отдельных элементов

Также можно настраивать цветовое оформление отдельных элементов. Например, для использования зелёного цвета фона и тёмной виртуальной клавиатуры, необходимо задать:
Рис. 40. Swift
theme.backgroundColor = UIColor.green
theme.showDarkKeyboard = true
Рис. 41. Objective-C
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 — включение светлых логотипов при использовании тёмной темы.