Mobile SDK Payment

Този SDK не само показва потребителския интерфейс за данни на картата, но също така взаимодейства с API на платежния шлюз. Освен това той обработва всички пренасочвания на 3DS и може да използва 3DS SDK като вграден. На търговеца му е по-лесно да интегрира плащания по този начин, но този SDK не е толкова гъвкав, колкото SDK Forms или SDK Core (няма възможност да се използват всички функции на платежния API).

Имайте предвид, че SDK Payment използва Mobile SDK 3DS2, а ACS на много издатели не работят правилно с Mobile SDK 3DS2.

Методи за плащане, поддържани от този SDK:

Метод за плащане	Поддръжка
Банкова карта	Да
Запазени идентификационни данни/карта	Да
Apple Pay	Да
Google Pay	Да

Повече за SDK Payment

Процес на плащане SDK Payment

Web View за 3DS

На диаграмата по-долу е показан процесът на плащане SDK Payment с пренасочване на 3DS чрез Web View.

sequenceDiagram participant MA as Мобилно приложение participant MS as Мобилен сървър participant SDK as SDK participant PG as Платежен шлюз MA ->> MS: 1. клиент създава поръчка MS ->> PG: 2. регистрация на поръчка чрез API PG -->> MS: 3. уникален номер на поръчка (mdOrder) MA ->> SDK: 4. инициализация на SDK Payment SDK ->> SDK: 5. клиент въвежда данни SDK -->> PG: 6. изпращане на seToken PG ->> PG: 7. плащане (включва 3DS) opt Callback-уведомления са конфигурирани PG -->> MS: 8. callback-уведомление end MS ->> PG: 9. проверка на статуса на плащането MS ->> MA: 10. показване на резултата от плащането на клиента

Клиентът създава поръчка
Мобилният сървър регистрира тази поръчка в платежния шлюз чрез register.do. Използвайте параметъра returnUrl като маркер за затваряне на Web View след пренасочване от ACS.
Мобилният сървър получава в отговор уникалния номер на поръчката mdOrder.
Мобилното приложение инициира SDK Payment за събиране на платежните данни на клиента.
Клиентът попълва платежните данни.
SDK изпраща криптираните платежни данни (seToken) в платежния шлюз.
Платежният шлюз осъществява плащането.
- Ако се изисква, платежният шлюз осигурява връзка с 3D Secure.
- За обработка на плащания с 3DS 2 препоръчваме да използвате пренасочване чрез web view (use3ds2sdk=false).
Платежният шлюз изпраща уведомление за обратно повикване на сървъра на търговеца, ако е конфигурирано за търговеца.
Мобилният сървър проверява окончателния статус на плащането чрез getOrderStatusExtended.do.
Мобилното приложение показва резултата от плащането на клиента.

iOS

По-долу е описана настройката на проекта. Framework-ът може да бъде инсталиран ръчно.

SDKPayment се основава на framework-ите ThreeDSSDK, SDKForms. Затова те са необходими за импортиране.

За да инсталирате framework-ите ръчно, изтеглете и ги добавете в проекта.

iOS-интеграция

Интеграция SDKForms.framework

Можете да интегрирате SDKForms.framework по следния начин:

Добавете SDKForms.framework и SDKCore.framework ръчно.

SDKForms.framework

Изтеглете най-новата версия на framework-ите тук.
Изберете файловете SDKCore.framework и SDKForms.framework, а след това ги добавете в папката на проекта.

Фигура 1. Добавяне на файл SDKForms.framework

Отворете страницата Targets -> General -> Frameworks, Libraries, and Embedded Content. За SDKCore.framework и SDKForms.framework в колоната Embed заменете Do not Embed с Embed & Sign.

Фигура 2. Промяна на свойствата SDKForms.framework

След това импортирайте framework-а във файла ViewController.swift.

Интеграция SDKPayment.framework

SDKPayment.framework

Изтеглете най-новата версия на framework-ите тук.
Изберете изтеглените файлове и ги добавете в папката на проекта.

Фигура 3. Добавяне на файл SDKPayment.framework

Отворете страницата Targets -> General -> Frameworks, Libraries, and Embedded Content. В колоната Embed за framework-ите заменете Do not Embed с Embed & Sign.

Фигура 4. Промяна на свойствата SDKPayment.framework

След това импортирайте framework-а във файла ViewController.swift.

//ViewController.swift
...
import SDKPayment
...

Работа с API V1

Конфигурация на SDK

За инициализация е необходимо да се зададе адреса на сървъра на платежната шлюза.

final class MainViewController: UIViewController {

    private func checkout() {
      SdkPayment.initialize(
        sdkPaymentConfig: SDKPaymentConfig(
          baseURL: "\(baseApiUrl)",
          use3DSConfig: .noUse3ds2sdk,
          keyProviderUrl: "\(baseApiUrl)/se/keys.do"
        )
      )
      ...
    }
  }

При използване на API V1 трябва да регистрирате нов обект order. При регистрация на order заявката трябва да съдържа параметър returnUrl равен на "sdk://done".

За използване на метода checkoutWithBottomSheet() е необходимо да създадете CheckoutConfig с mdOrder.

final class MainViewController: UIViewController {

    private func checkout() {
      ...
      // Creating `CheckoutConfig`
      let checkoutConfig = CheckoutConfig(id: .mdOrder(id: mdOrder))

      SdkPayment.shared.checkoutWithBottomSheet(
          controller: navigationController!,
          checkoutConfig: checkoutConfig,
          callbackHandler: self
      )
    }
  }

Обработка на резултата от плащането

За MainViewController е необходимо да се реализират изискванията на ResultPaymentCallback.

extension MainViewController: ResultPaymentCallback {

    typealias T = PaymentResult

    func onResult(result: PaymentResult) {
      print("\(result.isSuccess) \(result.paymentId)")
    }
  }

Android

SDKPayment е базиран на фреймуорките ThreeDSSDK, SDKForms. Затова те са необходими за импорт.

Android-интеграция

Свързване към Gradle проект чрез добавяне на .aar файлове на библиотеката

Необходимо е да добавите файла на библиотеката sdk_forms-release.aar в папката libs, а след това да укажете зависимостта на добавената библиотека.

build.gradle.kts

allprojects {
  repositories {
    // ...
    flatDir {
      dirs("libs")
    }
  }
}

dependencies {
  // dependency is mandatory to add
  implementation(group = "", name = "sdk_forms-release", ext = "aar")

  implementation("androidx.cardview:cardview:1.0.0")
  implementation("com.github.devnied.emvnfccard:library:3.0.1")
  implementation("com.caverock:androidsvg-aar:1.4")
  implementation("io.card:android-sdk:5.5.1")
  implementation("com.google.android.gms:play-services-wallet:18.0.0")
}

build.gradle

allprojects {
  repositories {
    // ...
    flatDir {
      dirs 'libs'
    }
  }
}

dependencies {
  // dependency is mandatory to add
  implementation(group = "", name = "sdk_forms-release", ext = "aar")
  implementation("androidx.cardview:cardview:1.0.0")
  implementation("com.github.devnied.emvnfccard:library:3.0.1")
  implementation("com.caverock:androidsvg-aar:1.4")
  implementation("io.card:android-sdk:5.5.1")
  implementation("com.google.android.gms:play-services-wallet:18.0.0")
}

Свързване към Gradle проект чрез добавяне на .aar файлове на библиотеката

Необходимо е да добавите файла на библиотеката sdk_payment-release.aar в папката libs, а след това да укажете зависимостта на добавената библиотека.

build.gradle.kts

allprojects {
    repositories {
        // ...
        flatDir {
            dirs("libs")
        }
    }
}

dependencies {
    // dependency is mandatory to add
    implementation(group = "", name = "sdk_payment-release", ext = "aar")
}

build.gradle

allprojects {
    repositories {
        // ...
        flatDir {
            dirs 'libs'
        }
    }
}

dependencies {
    // dependency is mandatory to add
    implementation(group = "", name = "sdk_payment-release", ext = "aar")
}

Работа с API V1

Конфигурация на SDK

За инициализация е необходимо да зададете адреса на сървъра на платежния шлюз.

SDKPayment.init(
  SDKPaymentConfig(
    baseURL = "https://uat.dskbank.bg/payment/rest",
  )
)

При използване на API V1 е необходимо да регистрирате нов обект order. При регистрация на order заявката трябва да съдържа параметъра returnUrl и да не съдържа никакви други параметри с Url, като failUrl. returnUrl трябва да има стойност "sdk://done".

// A link to an activity or a fragment is required. Checkout config is required.
  val checkoutConfig = CheckoutConfig.MdOrder("eecbbe96-973e-422e-a220-e9fa8d6cb124")
  SDKPayment.checkout(activity = this, checkoutConfig = checkoutConfig)

Базов URL-адрес за достъп до методите на платежния шлюз и корневия сертификат за проверка на подписа се указват чрез обект от класа SDKPaymentConfig.

Методът за плащане е достъпен в два варианта, извиквани от Activity и Fragment:

checkout(activity: Activity, checkoutConfig: CheckoutConfig)
checkout(fragment: Fragment, checkoutConfig: CheckoutConfig)

Обработка на резултата от плащането

За Activity и Fragment е необходимо да се предефинира методът onActivityResult.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // Processing the result of the payment cycle. 
    SDKPayment.handleCheckoutResult(requestCode, data, object :
        ResultPaymentCallback<PaymentData> {
          override fun onResult(result: PaymentResult) {
            // check payment result
          }
    })
}

При успешно плащане се връща обект PaymentResult, съдържащ текстово поле isSuccess от формат boolean, съдържащо резултата от плащането, както и незадължително поле exception.

Примери на екрани


Плащане с карта	Потвърждение 3DSecure

Фигура 7. Плащане с нова карта


Запазени карти	Потвърждение CVC	Потвърждение 3DSecure

Фигура 8. Плащане с прикачена карта

Плащане чрез Google Pay модул SDK Payment

За извършване на плащане чрез Google Pay модул SDK е необходимо да се извика начинът за плащане checkout(), предавайки стойност true на флага gPayClicked. Стойността по подразбиране е false.

fun checkout(activity: Activity, checkoutConfig: CheckoutConfig, gPayClicked: Boolean = false) {
}

Екрани с платежни бутони на портфейли

Фигура 9. Дизайн на бутона Google Pay

Логиране

Вътрешните процеси се логират с таг SDK-Core. Можете също така да логирате вашите процеси.

Логирането е достъпно чрез обекта Logger.

За добавяне на log- интерфейси е необходимо да се извика Logger-методът addLogInterface().

Пример за логиране в LogCat:

...
    Logger.addLogInterface(object : LogInterface {
        override fun log(classMethod: Class<Any>, tag: String, message: String, exception: Exception?) {
                Log.i(tag, "$classMethod: $message", exception)
            }
        })
...

По подразбиране се използва тагът SDK-Core. Можете да зададете ваш собствен, ако искате.

За регистрация на собствени събития е необходимо да се извика Logger-методът log().

Пример: ... Logger.log(this.javaClass, "MyTag", "My process...", null) ...

Често задавани въпроси

Q: Какво е CardIOUtilities?
A: CardIOUtilities - това е интерфейс на библиотеката CardIO. Можете да прочетете ръководството тук: https://github.com/card-io/card.io-iOS-source.