SDK Core для iOS

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

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

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

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

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

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

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

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

SDK Core для iOS поддерживает проведение оплат (ApplePaySaleRequest) и блокировку средств (ApplePayAuthRequest) с использованием метода 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 для проекта мобильного приложения в используемой среде разработки.

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

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

• 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"}}")