SDK для iOS

SDK для iOS — это набор средств разработки для подключения мобильных приложений, работающих на платформе iOS, к платёжной платформе ECommPay. В этом разделе представлена информация о работе с SDK для iOS версии 1.8, с примерами кода на языках программирования Swift и Objective-C.

SDK для iOS можно встраивать в мобильные приложения, работающие на платформе iOS версии 10.0 или выше.

Для SDK для iOS версии 1.7.0 и выше поддерживается подключение библиотек через CocoaPods. Подробнее — в разделе Подключение библиотек через CocoaPods.

Также SDK для iOS можно загрузить с GitHub по следующим ссылкам:

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

Возможности

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

Состав

SDK для iOS содержит примеры работы на языках программирования Swift и Objective-C и три библиотеки:
  • universal — библиотека для разработки. Она поддерживает запуск на эмуляторе и физических устройствах, но не совместима с технологией Bitcode. Приложение, разработанное с использованием этой библиотеки, нельзя публиковать в App Store.
  • iphonesimulator — библиотека для проведения автоматизированного тестирования. Она поддерживает архитектуру процессоров x86 и x86–64. Приложение, разработанное с использованием этой библиотеки, нельзя публиковать в App Store.
  • iphoneos — библиотека для использования на устройствах Apple. Она поддерживает архитектуру ARM64 и совместима с технологией Bitcode. Приложение, разработанное с использованием этой библиотеки, можно публиковать в App Store.

Схема работы

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

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



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

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

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

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

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



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



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



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



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



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



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



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



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

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

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



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

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

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

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

Для подключения библиотек к проекту мобильного приложения необходимо:
  1. Перенести файл ecommpaySDK.framework в папку проекта мобильного приложения.
  2. Добавить библиотеку к проекту. В Xcode версии 9.0 для этого необходимо:
    1. Открыть цель (target) проекта.
    2. Перейти в General > Embedded Binaries.
    3. Щёлкнуть +.
    4. Щёлкнуть Add Other.
    5. Выбрать файл ecommpaySDK.framework.
    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.framework в папку проекта мобильного приложения.
  2. Добавить библиотеку к проекту. В Xcode версии 9.0 для этого необходимо:
    1. Открыть цель (target) проекта.
    2. Перейти в General > Embedded Binaries.
    3. Щёлкнуть +.
    4. Щёлкнуть Add Other.
    5. Выбрать файл ecommpaySDK.framework.
    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 и добавить в него строки для библиотеки, которую планируется использовать:
    • Библиотека iphoneos (для использования на устройствах Apple):
      target 'App' do
        # Pods for App
        pod 'Paymentpage-sdk-ios/Iphoneos', '1.7.0'
      end
    • Библиотека universal (для разработки):
      target 'App' do
        # Pods for App
        pod 'Paymentpage-sdk-ios/Universal', '1.7.0'
      end
    • Библиотека iphonesimulator (для проведения автоматизированного тестирования):
      target 'App' do
        # Pods for App
        pod 'Paymentpage-sdk-ios/IphoneSimulator', '1.7.0'
      end

    Если строка pod 'Paymentpage-sdk-ios', '1.7.0' добавлена без указания типа библиотеки (iphoneos, universal или iphonesimulator), по умолчанию подключается библиотека iphoneos.

    Более подробная информация об этих библиотеках представлена в разделе Состав.

  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.

    Пример объекта 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 — сохранённые ранее платёжные инструменты отображаются при открытии платёжной формы.
    • 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("ecommpaySDK 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/EcommpaySDK.h>
  2. Объявить библиотеку ecommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
    EcommpaySDK *ecommpaySDK = [[EcommpaySDK.h 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"];
    Дополнительно могут использоваться следующие объекты и параметры:
    • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
    • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
    • customerID — идентификатор пользователя, уникальный в рамках проекта.
    • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
    • token — токен карты.
    • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
    • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды поддерживаемых платежных методов на Payment Page.
    • 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);
         }
     }];

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

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

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

Рис.: Приём результатов в 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)")
   }
 }

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

Рис.: Swift

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

Рис.: 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:

Рис.: Swift

paymentInfo.setToken(token);

Рис.: Objective-C

[paymentInfo setToken:token];

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

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

Рис.: Фрагмент оповещения с токеном

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

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

Другим способом генерации токена является отправка запроса на генерацию токена. Для генерации токена необходимо задать Tokenize в типе действия:

Рис.: Swift

paymentInfo.setAction(action: .Tokenize)

Рис.: Objective-C

[paymentInfo setAction:ActionTypeTokenize];

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

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

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

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

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

Для проведения разовых двухстадийных оплат необходимо:
  1. Задать значение Auth в типе действия.

    Рис.: Swift

    paymentInfo.setAction(action: .Auth)

    Рис.: Objective-C

    [paymentInfo setAction:ActionTypeAuth];
  2. Подтвердить списание средств через Old Dashboard или с помощью запроса на /v2/payment/card/capture.

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

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

SDK для iOS поддерживает проведение повторяемых оплат. Такие оплаты бывают трёх типов: OneClick, автооплаты и регулярные оплаты. Подробнее о повторяемых оплатах — в разделе Общая информация.
Прим.: Регистрация повторяемых оплат при использовании SDK для iOS выполняется в рамках операций sale, auth и verify и поддерживается только для оплат с использованием платёжных карт.
Для проведения повторяемой оплаты необходимо:
  1. Создать объект RecurrentInfo с параметрами:
    • type — тип повторяемой оплаты (.OneClick, .Regular, или .Autopayment),
    • cardOperationType — тип операции, в рамках которой регистрируется повторяемая оплата. Возможные значения:
      • sale — оплата с прямым списанием средств,
      • auth — предварительная блокировка средств при проведении двухстадийной оплаты,
      • verify — проверка действительности платёжного инструмента.
    • expiryDay — день окончания действия подписки,
    • expiryMonth — месяц окончания действия подписки,
    • expiryYear — год окончания действия подписки,
    • period — периодичность проведения повторяемых оплат,
    • time — время проведения повторяемых оплат,
    • startDate — дата проведения первой повторяемой оплаты,
    • scheduledPaymentID — идентификатор повторяемой оплаты в проекте.

    Рис.: 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")

    Рис.: 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:

      Рис.: Swift

      recurrentInfo.setAmount(amount: 1000)

      Рис.: Objective-C

      [recurrentInfo setAmount:1000];
    • Дат и сумм списания. По умолчанию при повторяемых оплатах средства списываются с карты строго фиксированно по времени и сумме, но можно задать собственное расписание в объекте recurrentInfo:

      Рис.: Swift

      recurrentInfo.setSchedule(schedule: [
                 RecurrentInfoSchedule(date: "10-10-2020", amount: 1200),
                 RecurrentInfoSchedule(date: "10-11-2020", amount: 1000),
                 ...
      ])

      Рис.: Objective-C

      [recurrentInfo setSchedule:@[
                    [[RecurrentInfoSchedule alloc] initWithDate:@"10-10-2020" amount:1200],
                    [[RecurrentInfoSchedule alloc] initWithDate:@"10-11-2020" amount:1000],
                    ...
      ]];
  2. Добавить объект RecurrentInfo в объект PaymentInfo.

    Рис.: Swift

    paymentInfo.setRecurrent(recurrent: recurrentInfo)

    Рис.: Objective-C

    [paymentInfo setRecurret:recurrentInfo];

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

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

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

Рис.: Swift

paymentInfo.setAction(action: .Verify)

Рис.: Objective-C

[paymentInfo setAction:ActionTypeVerify];

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

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

SDK для iOS поддерживает проведение оплат с использованием альтернативных платёжных методов Skrill Wallet, DOKU Wallet, «QIWI Кошелёк», «Яндекс.Деньги», Apple Pay, Banks of Malaysia, Banks of Thailand, «Оплата в магазинах Таиланда», MCash Wallet, Alipay, Neteller, WebMoney (сценарии оплат WebMoneyLight и WebMoneyClassic). Описание каждого из этих методов представлено в отдельной статье, а схемы проведения оплат через SDK для iOS с использованием этих методов можно разбить на два типа: с подтверждением в сервисе альтернативной платёжной системы возможности проведения платежа (это актуально для Apple Pay) и с перенаправлением пользователя к сервису альтернативной платёжной системы для подтверждения и обработки платежа (это актуально для остальных методов). Далее представлены обе схемы, а также описание особенностей работы с методом Apple Pay и поддерживаемыми сценариями оплат метода WebMoney.

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

Рис.: Проведение оплаты с использованием 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 представлены в разделе Повторяемая оплата.

WebMoney

При работе с SDK для iOS поддерживается проведение оплат с использованием сценариев WebMoneyLight и WebMoneyClassic. При использовании WebMoneyLight осуществляется перенаправление пользователя к форме оплаты WebMoney для перевода средств на WM-кошелёк мерчанта. При использовании WebMoneyClassic пользователь самостоятельно переходит в сервис WebMoney для проведения оплаты. Все основные процедуры, такие как вызов платёжной формы, приём результатов и обработка оповещений, выполняются так же, как и при работе с другими платёжными методами, а при формировании запросов необходимо учитывать следующее:

  • Для сценария оплаты WebMoneyClassic поддерживается возможность автоматического инициирования оплаты без указания пользователем данных в платёжной форме. Для этого, помимо базового минимального набора параметров (подробнее: Вызов платёжной формы), мерчанту необходимо передать в запросе на открытие платёжной формы значения обоих следующих параметров:
    • accountNumber — идентификатор пользователя в сервисе WebMoney (WMID).
    • accountPurseType — тип кошелька WebMoney.

    Если в запросе переданы значения обоих указанных параметров, проведение оплаты инициируется автоматически без возможности для пользователя изменить указанные данные.

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

  • При проведении платежа необходимо использовать валюту, которая поддерживается методом WebMoney. Информация о поддерживаемых валютах представлена в разделе WebMoney.

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

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

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

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

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

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

Рис.: 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: "")
          ....
])

Рис.: 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 можно менять:
  • использовать светлую или тёмную тему,

    Рис.: Светлая тема платёжной формы



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



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

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

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

Рис.: Swift

let theme = ECPTheme.getDarkTheme()
ecompaySDK.setTheme(theme: theme)

Рис.: Objective-C

ECPTheme *theme = [ECPTheme getDarkTheme];
[self.ecommpaySDK setTheme:theme];

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

Также можно настраивать цветовое оформление отдельных элементов. Например, для использования зелёного цвета фона и тёмной виртуальной клавиатуры, необходимо задать:

Рис.: Swift

theme.backgroundColor = UIColor.green
theme.showDarkKeyboard = true

Рис.: 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 — включение светлых логотипов при использовании тёмной темы.