SDK Core для iOS

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

Введение

Mobile SDK Core для iOS — это набор средств разработки, который может использоваться для подключения к платёжной платформе ecommpay мобильных приложений, работающих на платформе iOS.

SDK Core для iOS позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой для отправки и приёма необходимой информации при проведении платежей. При этом SDK Core для iOS не обеспечивает интерфейсное взаимодействие с пользователем и при работе с ним можно использовать собственный платёжный интерфейс.

В этой статье представлена информация о работе с SDK Core для iOS с описанием схемы взаимодействия, сценариев проведения платежей, а также дополнительных возможностей с примерами кода на языке Swift.

SDK Core для iOS можно встраивать в мобильные приложения, работающие на платформе iOS версии 11 и выше. Библиотеки SDK Core для iOS и примеры кода расположены на GitHub по следующим ссылкам:

Возможности

SDK Core для iOS поддерживает работу с платёжными картами, а также альтернативным методом Apple Pay. Функционально SDK Core для iOS позволяет:

  • Проводить оплаты с незамедлительным списанием средств.
  • Осуществлять блокировку средств для последующего списания по истечении заданного периода, либо на основании подтверждающего запроса (через интерфейсы Gate или Dashboard).
  • Выполнять проверку платёжных карт для их дальнейшего использования.
  • Регистрировать проведение повторяемых оплат.
  • Сохранять платёжные данные для проведения последующих оплат.

При проведении платежей от пользователей могут требоваться дополнительные действия, например прохождение аутентификации 3‑D Secure и указание сведений о владельце платёжного инструмента. Необходимость выполнения этих действий, как правило, зависит от протоколов и правил провайдеров и платёжных систем, но в отдельных случаях может зависеть и от предпочтений мерчанта. SDK Core для iOS поддерживает работу со следующими процедурами и дополнительными возможностями:

  • Аутентификация 3‑D Secure — процедура аутентификации пользователей по протоколам 3‑D Secure.
  • Каскадное проведение платежей — дополнительные попытки проведения платежей (когда это актуально) без изменения способа оплаты.
  • Дополнение информации о платежах — процедура указания дополнительных данных, которые могут запрашиваться платёжными системами в некоторых случаях.
  • Сбор данных о пользователях — получение и предоставление дополнительной информации о пользователях, которая может быть актуальна при проведении последующих платежей.

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

Схема работы

В общем случае проведение оплат с использованием SDK Core для iOS выполняется согласно следующей схеме.

  1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом.
  2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK Core для iOS этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервиса мерчанта.
  3. В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK Core для iOS.
  4. С помощью SDK Core для iOS инициируется создание платёжной сессии в платёжной платформе.
  5. На стороне платёжной платформы на основе идентификаторов проекта и пользователя формируются и отправляются к SDK Core для iOS списки с доступными платёжными методами и сохранёнными платёжными данными.
  6. В мобильном приложении выполняется обработка полученной от SDK Core для iOS информации и её подготовка для отображения пользователю.
  7. Пользователь выбирает платёжный метод (если он не был задан при открытии платёжной сессии), указывает необходимую информацию и подтверждает готовность провести оплату.
  8. В мобильном приложении выполняется вызов конкретного сценария работы с SDK Core для iOS — с учётом всех действий, выполненных пользователем.
  9. От SDK Core для iOS к платёжной платформе отправляется запрос на проведение оплаты по заданному сценарию.
  10. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам и платёжным системам.
  11. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате.
  12. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты.
  13. От платёжной платформы к SDK Core для iOS направляется информация о результате оплаты.
  14. Уведомление с информацией о результате передаётся от SDK Core для iOS к мобильному приложению и далее отображается пользователю.

Подготовка к использованию

Порядок интеграции

Для подключения веб-сервиса к платёжной платформе ecommpay с использованием SDK Core для iOS со стороны мерчанта необходимо:

  1. Решить организационные вопросы, касающиеся взаимодействия с ecommpay:

    1. Если у компании нет идентификатора и ключа для взаимодействия с ecommpay — отправить заявку на подключение.
    2. Если у компании есть идентификатор и ключ для взаимодействия с ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK Core для iOS и согласовать порядок тестирования и запуска.
  2. Выполнить подготовительные технические работы:

    1. Скачать и подключить SDK Core для iOS.
    2. Подготовить пользовательский интерфейс и обеспечить сбор данных, необходимых для инициирования платёжной сессии. Минимальный набор данных, который необходимо собрать для создания платёжной сессии, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа.
    3. Обеспечить подписывание данных на стороне серверной части мобильного приложения.
    4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK Core для iOS, а также оповещения от платёжной платформы.
  3. Согласовать со специалистами технической поддержки ecommpay порядок и сроки интеграции, тестирования (в том числе с использованием доступных платёжных методов) и запуска решения в работу.

    1. Для тестирования следует использовать идентификатор тестового проекта и данные тестовых карт.
    2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от ecommpay.

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

Установка библиотек

Для приложений, работающих на платформе iOS 11 и выше поддерживается подключение библиотек SDK Core для iOS через CocoaPods. Чтобы подключить библиотеки, необходимо выполнить следующее:

  1. Открыть файл Podfile и добавить в него следующие строки:
    target 'App' do
        pod 'MsdkCore'
    end
  2. Выполнить команду pod install.
  3. Импортировать библиотеку с помощью команды import MsdkCore.

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

Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования (подробнее), либо собственные решения, реализованные на стороне мерчанта. Порядок работы с подписью представлен в разделе Работа с подписью к данным.

Тестирование

Перед проведением реальных платежей через SDK Core для iOS рекомендуется протестировать проведение платежей с использованием тестового проекта. Идентификатор тестового проекта и секретный ключ для него можно получить при подключении к тестовой среде ecommpay (сделать это можно через сайт компании). Также по согласованию со специалистами ecommpay можно протестировать использование метода Apple Pay и дополнительных возможностей, таких как каскадное проведение платежей и сбор данных о пользователях.

Для перехода в тестовый режим проведения платежей необходимо:

  1. Перейти в папку проекта и выполнить команду pod install.
  2. Открыть проект через iosApp.xcworkspace.
  3. В файле Info.plist указать идентификатор тестового проекта (PROJECTID) и секретный ключ от него (PROJECT_SECRET_KEY).

Чтобы перейти в рабочий режим, необходимо заменить тестовые значения (идентификатор рабочего проекта и секретный ключ от него) на рабочие.

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

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

Сценарии, порядок выполнения целевых действий, а также набор параметров, доступных при работе с SDK Core для iOS, представлены в следующих разделах этой статьи.

Порядок выполнения целевых действий

SDK Core для iOS поддерживает выполнение целевых действий с прямым использованием карт, а также использованием альтернативного метода Apple Pay (подробнее). Для работы с платёжным методом Apple Pay предварительно необходимо связаться со специалистами службы технической поддержки ecommpay и согласовать его подключение.

Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Для таких случаев становится обязательным передавать номер телефона пользователя или адрес его электронной почты. По крайней мере один из этих параметров необходимо указывать при отправке запроса на создание платёжной сессии.

Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения.

В общем случае для проведения оплат через SDK Core для iOS со стороны мерчанта необходимо выполнить следующее:

  1. Создать объект MSDKCoreSession.
    let msdkConfig = MSDKCoreSessionConfig.companion.debug(apiHost: "API HOST", wsApiHost: "WS API HOST")
    let msdkSession = MSDKCoreSession(config: msdkConfig)
  2. Создать объект PaymentInfo с параметрами проведения платежа. В объекте должен содержаться обязательный минимум параметров (идентификатор проекта, платежа и пользователя, а также сумма и валюта платежа), дополнительно также могут быть переданы и другие параметры (подробнее).
    let paymentInfo = PaymentInfo.companion.create // информация о платеже
    (
    projectId: 553,             // идентификатор проекта
    paymentId: "payment_21",    // идентификатор платежа
    customerId: "12",           // идентификатор пользователя
    paymentAmount: 400,         // сумма платежа
    paymentCurrency: "EUR"      // код валюты платежа
    )
    
  3. Получить строку для подписывания параметров и передать её в серверную часть приложения.
    paymentInfo.getParamsForSignature(),
  4. На стороне серверной части приложения подписать итоговый набор параметров и передать его в клиентскую часть.
  5. Добавить подпись в объект PaymentInfo.
  6. Отправить запрос на создание платёжной сессии. Для этого необходимо запустить выполнение метода getInitInteractor.

    На этом шаге указываются параметры для аутентификации 3‑D Secure, если они необходимы. Для выполнения аутентификации может потребоваться указать адрес электронной почты пользователя (customerEmail) или его номер телефона (customerPhone). Кроме того, рекомендуется указать сведения о платёжном адресе пользователя:

    • billingCountry — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 (подробнее);
    • billingPostal — индекс платёжного адреса пользователя;
    • billingCity — название города платёжного адреса пользователя;
    • billingAddress — название улицы платёжного адреса пользователя.
    let request = InitRequest(
         paymentInfo: paymentInfo,
         recurrentInfo: nil,      
         additionalFields: [  //список полей для запрашивания дополнительной информации
            "customerEmail": customerEmail,
            "customerPhone": customerPhone
         ] as [String: Any]
    )
    msdkSession.getInitInteractor().execute(
        request: request,
        callback: self
    )
  7. Принять уведомление с информацией о создании платёжной сессии, а также списками доступных платёжных методов и сохранённых платежных данных, актуальных для используемого проекта и конкретного пользователя.
    func onInitReceived(paymentMethods: [PaymentMethod], savedAccounts: [SavedAccount]) {
        let stringResourceManager = msdkSession.getStringResourceManager()
        let title = stringResourceManager?.payment.methodsTitle
              
        let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
        let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa")
              
        let paymentMethods = msdkSession.getPaymentMethods()    // получение списка платёжных методов
        let savedAccounts = msdkSession.getSavedAccounts()    // получение списка сохранённых платёжных данных
    }
  8. Обработать полученные данные и отобразить пользователю форму оплаты.
  9. Для проведения оплат через Apple Pay необходимо выполнить следующее:
    • Получить токен от Apple Pay. Для этого можно использовать класс PKPaymentRequest, который позволяет взаимодействовать с PassKit.
      let supportedPaymentNetworks = [PKPaymentNetwork.visa, PKPaymentNetwork.masterCard]
      let paymentItem = PKPaymentSummaryItem(label: "MSDK Pay", amount: NSDecimalNumber(value: 1.23))
       
      if PKPaymentAuthorizationViewController.canMakePayments(usingNetworks: supportedPaymentNetworks) {
          let request = PKPaymentRequest()
          request.currencyCode = "EUR"
          request.countryCode = "GB"
          request.merchantIdentifier = "merchant_id"
          request.merchantCapabilities = PKMerchantCapability.capability3DS
          request.supportedNetworks = supportedPaymentNetworks
          request.paymentSummaryItems = [paymentItem]
           
          guard let paymentVC = PKPaymentAuthorizationViewController(paymentRequest: request) else {
              return
          }
          paymentVC.delegate = self
          self.present(paymentVC, animated: true, completion: nil)
      }
    • Получить в уведомлении PKPaymentAuthorizationViewControllerDelegate токен.
      var completion: ((PKPaymentAuthorizationResult) -> Void)?
       
      func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, 
      didAuthorizePayment payment: PKPayment, handler completion: 
      @escaping (PKPaymentAuthorizationResult) -> Void) {
          self.completion = completion
          let token = String(decoding: payment.token.paymentData, as: UTF8.self)
          }
  10. Отправить запрос на создание платежа с учётом полученных от пользователя данных. Для этого необходимо запустить выполнение метода getPayInteractor.
    // оплата с использованием карты
        override func viewDidLoad() 
    {
        super.viewDidLoad()
        // сценарий проведения оплаты с использованием карты
        AppDelegate.msdkSession?.getPayInteractor().execute
            (request: NewCardSaleRequest    
                (   cvv: "123",
                    pan: "5413330000000019",
                    expiryDate = CardDate(month = 1, year = 2025),
                    cardHolder: "John Doe",
                    saveCard: false
                ), 
        callback: self)
    }
         
        // оплата с использованием метода Apple Pay    
        AppDelegate.msdkSession?.getPayInteractor().execute
            (request: ApplePaySaleRequest.init
                (    token: token    // токен, полученный от Apple Pay
                    ), 
        callback: self
  11. Принять ряд уведомлений от SDK Core для iOS: о создании платежа и об изменении статуса платежа. Если актуально, также принять уведомления о необходимости дополнения информации о платеже и прохождения аутентификации с использованием протокола 3‑D Secure и выполнить требуемые действия.
  12. Принять уведомление с информацией о результате платежа и отобразить эту информацию пользователю.

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

Параметры работы с SDK Core для iOS

Действия с платёжными картами

Для выполнения таких целевых действий с прямым использованием карт, как проведение оплат (NewCardSaleRequest), выполнение блокировок средств (CardAuthRequest) и проверок действительности карт (CardVerifyRequest), используются следующие наборы данных.

Создание платёжной сессии Создание платежа
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • payment_id (string) — идентификатор платежа, уникальный в рамках проекта
  • payment_amount (integer) — сумма платежа в дробных единицах валюты (для проверки действительности необходимо указывать 0)
  • payment_currency (string) — код валюты платежа в формате ISO 4217 alpha-3
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • register (boolean) — признак регистрации повторяемых оплат, для которого необходимо использовать значение true. Информация о параметрах, доступных для регистрации повторяемых оплат представлена в отдельной статье
  • cvv (string) — код проверки подлинности карты
  • pan (string) — номер карты (без указания пробелов)
  • year (integer) — год окончания срока действия карты
  • month (integer) — месяц окончания срока действия карты
  • cardHolder (string) — имя держателя, указанное на карте
  • saveCard (boolean) — признак сохранения данных платёжной карты

Формирование токенов

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

Для формирования токенов через SDK Core для iOS необходимы следующие наборы данных.

Создание платёжной сессии Формирование токена
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • pan (string) — номер карты (без указания пробелов)
  • year (integer) — год окончания срока действия карты
  • month (integer) — месяц окончания срока действия карты
  • cardHolder (string) — имя держателя, указанное на карте

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

SDK Core для iOS поддерживает возможности сохранения платёжных данных по инициативе пользователей и через формирование токенов, а также использования этих данных для проведения платежей. С использованием сохранённых платёжных данных и токенов можно проводить оплаты и выполнять блокировку средств через определённые сценарии. В случае с сохранёнными платёжными данными используются сценарии SavedCardSaleRequest (для оплат) и SavedCardAuthRequest (для блокировок), а в случае с токенами — CardSaleTokenizeRequest (для оплат) и CardAuthTokenizeRequest (для блокировок).

Создание платёжной сессии Создание платежа
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • payment_id (string) — идентификатор платежа, уникальный в рамках проекта
  • payment_amount (integer) — сумма платежа в дробных единицах валюты
  • payment_currency (string) — код валюты платежа в формате ISO 4217 alpha-3
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • account_token (string) — токен платёжных данных (используется для сценариев с участием токена)
  • cvv (string) — код проверки подлинности карты
  • accountId (integer) — идентификатор сохранённых платёжных данных, полученный в уведомлении о создании платёжной сессии

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

SDK Core для iOS поддерживает проведение оплат (ApplePaySaleRequest) и блокировку средств (ApplePayAuthRequest) с использованием метода Apple Pay.

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

Создание платёжной сессии Создание платежа
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • payment_id (string) — идентификатор платежа, уникальный в рамках проекта
  • payment_amount (integer) — сумма платежа в дробных единицах валюты
  • payment_currency (string) — код валюты платежа в формате ISO 4217 alpha-3
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • token — токен, полученный от Apple Pay
  • recepientInfo — объект, содержащий сведения о пользователе; используется для оплат с целью погашения задолженностей (ApplePayAuthRequest)

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

Кроме обязательного минимума параметров в запросах могут использоваться и дополнительные.

  • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
  • paymentDescription (string) — описание платежа.
  • regionCode (string) — код страны в формате ISO 3166 alpha-2.
  • token (string) — токен платёжных данных.
  • forcePaymentMethod (string) — код предварительно выбранного платежного метода. Коды платёжных методов доступны в справочнике.
  • hideSavedWallets (boolean) — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости не отображать пользователю сохранённые платёжные инструменты. Возможные значения:
    • true — сохранённые платёжные данные не отображаются пользователю.
    • false — сохранённые платёжные данные отображаются пользователю.

Дополнительные возможности

Сохранение платёжных данных

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

В результате сохранения платёжных данных по инициативе пользователя для каждого платёжного инструмента формируется идентификатор (account_id), ассоциированный с идентификатором конкретного пользователя (customer_id). В дальнейшем идентификаторы платёжных инструментов можно получить в уведомлении от SDK Core для iOS о создании платёжной сессии и использовать в запросе на создание платежа.

Если сохранение платёжных данных выполнялось в результате выполнения сценария CardTokenizeRequest, для конкретной платёжной карты пользователя формируется токен, который можно получить в уведомлении о формировании токена в объекте Payment и в дальнейшем указывать этот токен в запросах на проведение платежей. Для выполнения сценария формирования токена в запросе на создание сессии в SDK Core для iOS со стороны мерчанта необходимо указать идентификаторы проекта и пользователя, остальные данные для формирования токена (номер и срок действия платёжной карты, а также имя держателя карты) — запросить у пользователя.

Рис.: Пример сохранённых платёжных данных

"SavedAccounts":
{
  "number": "541333******0019",
  "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // токен платёжных данных
  "id": 12353661,   // идентификатор сохранённых платёжных данных (accountId)
  "last_deposit_date": "2022-04-22 06:22:33",
  "last_tokenize_date": null,
  "type": "card",
  "additional": {
    "email": "john@example.com",
    "phone": "+79012345678",
    "country": "RU",
    "recurring_enable": false,
    "card": {
      "holder": "Jonh Doe",
      "country": "RU",
      "bank_name": "CIAGROUP",
      "type": "mastercard",
      "product_name": "PREPAID",
      "expiry": "02/24"
    }
  },

Аутентификация 3‑D Secure

В случаях, когда для проведения платежей требуется выполнить аутентификацию пользователей по протоколам 3‑D Secure, со стороны мерчанта необходимо:

  1. Принять от SDK Core для iOS уведомление onThreeDSecure о необходимости отображения пользователю страницы аутентификации. В уведомлении содержится объект acsPage с параметрами отображения страницы аутентификации и ссылкой для перенаправления пользователя после прохождения аутентификации.
  2. Отобразить пользователю страницу аутентификации.
  3. Дождаться перенаправления пользователя со страницы аутентификации и вызвать метод threeDSecureHandled.
func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // вызов метода
}

Каскадное проведение платежей

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

Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK Core для iOS поступает уведомление, в котором содержится объект isCascading со значением true, что означает, что в рамках каскадного проведения платежей доступно выполнение дополнительной попытки. Если для проведения платежа необходима аутентификация пользователя, со стороны мерчанта требуется отобразить пользователю информацию об ошибке, получить от него подтверждение о выполнении очередной попытки и повторить проведение платежа. Если аутентификация не требуется, дополнительные действия со стороны мерчанта не выполняются.

func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment)
{
    interactor.threeDSecureHandled()  
}

Дополнение информации о платежах

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

Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Список параметров, актуальных для конкретного платежа поступает в уведомлении от SDK Core для iOS после отправки запроса на создание платежа (GetPayInteractor). Со стороны мерчанта необходимо обеспечить отображение пользователю полей для заполнения запрашиваемых данные, а затем передать полученные значения к SDK Core для iOS.

func onClarificationFields(clarificationFields: [ClarificationField], payment: Payment) { // получение списка запрашиваемых данных
    interactor.sendClarificationFields(clarificationFields) // передача полученных от пользователя данных
}

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

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

После получения от SDK Core для iOS уведомления со списком запрашиваемых параметров со стороны мерчанта необходимо отобразить пользователю в форме оплаты поля для заполнения. Далее полученные значения необходимо передать к SDK Core для iOS и продолжить проведение платежа.

func onCustomerFields(customerFields: [CustomerField]) { // получение списка запрашиваемых данных
    interactor.sendCustomerFields(customerFields) // передача полученных от пользователя данных
}

Приём уведомлений

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

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

  • onInitReceived — создание платёжной сессии в платёжной платформе ecommpay.
    func onInitReceived(paymentMethods: [PaymentMethod], savedAccounts: [SavedAccount]) {
        let stringResourceManager = msdkSession.getStringResourceManager()
        let title = stringResourceManager?.payment.methodsTitle
             
        let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
        let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa")
             
        let paymentMethods = msdkSession.getPaymentMethods()
        let savedAccounts = msdkSession.getSavedAccounts() ?? []
    }
  • onPaymentRestored — создание платёжной сессии с идентификатором платежа, который использовался ранее. Если платежу ещё не присвоен итоговый статус, можно использовать метод PaymentRestoreRequest и продолжить проведение инициированного ранее платежа.
    override func viewDidLoad() {
            super.viewDidLoad()
            AppDelegate.msdkSession?.getPayInteractor().execute(request: PaymentRestoreRequest(), callback: self)
        }
  • onError — возникла ошибка.
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")

Информирование о платеже

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

  • onPaymentCreated — создание платежа.
  • onStatusChanged — изменение статуса платежа.
  • onCustomerFields — необходимость в указании дополнительных данных о пользователе.
  • onThreeDSecure — необходимость в выполнении аутентификации по протоколу 3‑D Secure.
  • onClarificationFields — необходимость в дополнении информации о платеже.
  • onCompleteWithSuccess — платёж проведён.
  • onCompleteWithFail — получен отказ в проведении платежа.
  • onCompleteWithDecline — платёж отклонён.
  • onError — возникла ошибка.
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")

Реагирование на ошибки

В случае, если при обработке запросов возникают ошибки, от SDK Core для iOS поступают соответствующие уведомления. Возможные ошибки, причины их появления и предусмотренные для них дальнейшие действия со стороны мерчанта приведены в таблице.

Ошибка Возможная причина Рекомендуемые действия
CLARIFICATION_FIELDS_ERROR В рамках выполнения процедуры дополнения информации о платеже переданы некорректные данные Повторить заполнение дополнительных данных
CUSTOMER_ID_NOT_EXIST В запросе на формирование токена или проверку действительности платёжной карты не передан обязательный параметр customerId Скорректировать запрос
ILLEGAL_ARGUMENTS В запросе переданы некорректные значения Скорректировать запрос
INTERACTOR_NOT_RUNNING Выполнение действия, доступного в рамках проведения платежа, до его инициирования (например, передача дополнительных данных о пользователе до отправки запроса на создание платежа) Отправить запрос на создание платежа
NETWORK_ERROR Ошибка соединения Следует связаться со специалистами технической поддержки
NETWORK_IS_NOT_AVAILABLE Сеть недоступна Повторить запрос позже
NETWORK_TIMEOUT Выполнение запроса отклонено из-за превышения допустимого времени ожидания Повторить запрос позже
PAYMENT_ALREADY_EXIST Выполнение запроса отклонено из-за указания идентификатора платежа, который уже использовался ранее Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса
PAYMENT_HAS_FINAL_STATUS Выполнение запроса отклонено из-за указания в запросе идентификатора платежа, которому уже присвоен итоговый статус Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса
PAYMENT_METHOD_NOT_AVAILABLE Выполнение запроса отклонено из-за указания в запросе платёжного метода, недоступного в рамках используемого проекта Указать доступный в рамках проекта платёжный метод и повторить отправку запроса
PAYMENT_NOT_FOUND Не найден объект Payment Повторить выполнение запроса. В случае возникновения ошибки обратиться к специалистам технической поддержки.
PAYMENT_TOKEN_NOT_EXIST В запросе на проведение оплаты или проверки действительности платёжной карты с использованием токена не передан токен платёжных данных Указать токен платёжных данных и повторить отправку запроса
SERVER_API_ERROR Ошибка на стороне SDK Core для iOS Следует связаться со службой технической поддержки
SESSION_NOT_INITIALIZED Выполнение запроса отклонено из-за попытки выполнить какой-либо сценарий до создания платёжной сессии Инициировать создание платёжной сессии (InitInteractor)
SERVER_CONTENT_PARSING_ERROR Не удалось преобразовать ответ от сервера Скорректировать запрос
SERVER_METHOD_NOT_FOUND Вызов метода, который не предусмотрен для работы с SDK Core для iOS Скорректировать запрос
SERVER_UNAUTHORIZED Возникла ошибка соединения Повторить запрос позже