SDK Core for iOS

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

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

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

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

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

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

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

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

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

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

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

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

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

Если сохранение платёжных данных выполнялось в результате выполнения сценария CardTokenizeRequest, для конкретной платёжной карты пользователя формируется токен, который можно получить в уведомлении о формировании токена в объекте Payment и в дальнейшем указывать этот токен в запросах на проведение платежей. Для выполнения сценария формирования токена в запросе на создание сессии в SDK Core for 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 for iOS уведомление onThreeDSecure о необходимости отображения пользователю страницы аутентификации. В уведомлении содержится объект acsPage с параметрами отображения страницы аутентификации и ссылкой для перенаправления пользователя после прохождения аутентификации.
2. Отобразить пользователю страницу аутентификации.
3. Дождаться перенаправления пользователя со страницы аутентификации и вызвать метод threeDSecureHandled.

func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // вызов метода
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• onInitReceived — создание платёжной сессии в платёжной платформе Flashpay.

  func onInitReceived(savedAccounts: [SavedAccount]) {
      let stringResourceManager = msdkSession.getStringResourceManager()
      let title = stringResourceManager?.payment.methodsTitle
           
      let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
      let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa")
       
      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"}}")