SDK Core для Android

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

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

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

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

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

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

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

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

SDK Core для Android поддерживает проведение оплат (GooglePaySaleRequest) и блокировку средств (GooglePayAuthRequest) с использованием метода Google Pay.

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

1. Зарегистрироваться в сервисе Google Pay Business Console и получить идентификатор мерчанта в сервисе Google Pay (Google merchant ID).
2. Принять и соблюдать Правила допустимого использования Google Pay API, а также принять условия, приведённые в Пользовательском соглашении Google Pay API.
3. Встроить в пользовательский интерфейс кнопку Google Pay, соблюдая рекомендации по правильному использованию бренда, и реализовать процесс получения токена с карточными данными пользователя от сервиса Google Pay.
4. Добавить в файл AndroidManifest.xml следующую информацию:

   <meta-data
       android:name="com.google.android.gms.wallet.api.enabled"
       android:value="true" />

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

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

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

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

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

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

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

"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 для Android уведомление onThreeDSecure о необходимости отображения пользователю страницы аутентификации. В уведомлении содержится объект acsPage с параметрами отображения страницы аутентификации и ссылкой для перенаправления пользователя после прохождения аутентификации.
2. Отобразить пользователю страницу аутентификации.
3. Дождаться перенаправления пользователя со страницы аутентификации и вызвать метод threeDSecureHandled.

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

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

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

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

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

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

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

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

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

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

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

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

override fun onCustomerFields(customerFields: List<CustomerField>) {  // получение списка запрашиваемых данных
    interactor.sendCustomerFields(customFields) // передача полученных от пользователя данных
}

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

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

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

  override fun onInitReceived() {
      val stringResourceManager = msdkSession.getStringResourceManager()
      val title = stringResourceManager.payment.methodsTitle
    
      val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
      val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa")
    
      val paymentMethods = msdkSession.getPaymentMethods()
      val savedAccounts = msdkSession.getSavedAccounts()
  }

• onPaymentRestored — создание платёжной сессии с идентификатором платежа, который использовался ранее. Если платежу ещё не присвоен итоговый статус, можно использовать метод PaymentRestoreRequest и продолжить проведение инициированного ранее платежа.

  override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          setContentView(R.layout.activity_payment_restore)
          progressDialog = ProgressDialog(this@PaymentRestoreActivity)
          progressDialog.setMessage("Payment restoring")
          progressDialog.setCancelable(false)
          progressDialog.show()
  
          interactor.execute(PaymentRestoreRequest(), this)
      }

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