Процесс оплаты SDK Core

Web View для 3DS

На приведенной ниже диаграмме показан процесс оплаты SDK Core с перенаправлением 3DS через Web View.

1. Клиент создает заказ
2. Мобильный сервер регистрирует этот заказ в платежном шлюзе через register.do. Используйте параметр returnUrl в качестве маркера для закрытия Web View после перенаправления из ACS на Шаге 14.
3. Мобильный сервер получает в ответе уникальный номер заказа mdOrder.
4. Клиент заполняет платежные данные в мобильном приложении.

5. Мобильное приложение вызывает SDK для создания seToken. (Android: sdkCore.generateWithCard; iOS: CKCToken.generateWithCard).

   Публичный ключ, который требуется в соответствующем методе, необходимо брать с online ресурса https://3dsec.berekebank.kz/payment/se/keys.do. Если по этой ссылке доступно несколько ключей, следует использовать первый ключ. (Имейте в виду, что для тестовой и рабочей сред используются разные ключи.)

6. Мобильное приложение отправляет seToken на мобильный сервер.

7. Мобильный сервер использует этот seToken для совершения платежа через paymentorder.do.

   • Используйте seToken вместо pan, cvc и даты истечения срока действия.
   • Не забудьте указать имя держателя карты в поле TEXT. Если вы не собираете имя держателя карты, просто отправьте значение CARDHOLDER.

8. Мобильный сервер получает ответ без редиректа на ACS. Это означает, что оплата завершена и нам нужно перейти к Шагу 16.

9. Мобильный сервер получает ответ с редиректом на ACS.

10. Мобильное приложение открывает Web View с данными редиректа на ACS.

11. Клиент вводит свой одноразовый пароль в форму ACS.

12. ACS перенаправляет клиента на платежный шлюз.

13. Платежный шлюз осуществляет платеж.

14. Платежный шлюз перенаправляет клиента на returnUrl, который можно использовать в качестве маркера для закрытия Web View.

15. Мобильное приложение закрывает Web View.

16. Платежный шлюз отправляет уведомление обратного вызова на сервер продавца, если оно настроено для продавца.

17. Мобильный сервер проверяет окончательный статус платежа через getOrderStatusExtended.do.

18. Мобильное приложение показывает результат платежа клиенту.

3DS2 SDK для 3DS

На приведенной ниже диаграмме показан процесс оплаты SDK Core с перенаправлением 3DS через 3DS2 SDK. Имейте в виду, что ACS многих эмитентов неправильно работают с 3DS Mobile SDK.

1. Клиент создает заказ.
2. Мобильный сервер регистрирует этот заказ в платежном шлюзе через register.do. Используйте параметр returnUrl в качестве маркера для закрытия Web View после перенаправления из ACS на Шаге 14.
3. Мобильный сервер получает в ответе уникальный номер заказа mdOrder.
4. Клиент заполняет платежные данные в мобильном приложении.
5. Мобильное приложение вызывает SDK для создания seToken. (Android: sdkCore.generateWithCard; iOS: CKCToken.generateWithCard).
6. Мобильное приложение отправляет seToken на мобильный сервер.
7. Мобильный сервер использует этот seToken для совершения платежа через paymentorder.do.
   • Используйте seToken вместо pan, cvc и даты истечения срока действия.
   • Не забудьте указать имя держателя карты в поле TEXT. Если вы не собираете имя держателя карты, просто отправьте значение CARDHOLDER.
   • Передайте threeDSSDK=true, чтобы указать, что следует использовать 3DS2 SDK.
8. Мобильный сервер получает ответ без ключей ACS. Это означает, что оплата завершена и нужно перейти к Шагу 23.
9. Мобильный сервер получает ответ с ключами ACS.
   • Ответ должен содержать threeDSServerTransId и threeDSSDKKey.
   • Ответ не должен содержать threeDSMethodURL, который используется в случае перенаправления через браузер на ACS.
10. Мобильный сервер отправляет данные 3DS2 SDK в мобильное приложение.
11. Мобильное приложение инициирует 3DS2 SDK с помощью метода createTransaction.
    • directoryServerID зависит от платежной системы (для тестов можно использовать значение A000000003.)
    • messageVersion на данный момент – 2.1.0.
    • pemPublicKey для Android и iOS – это сертификат pem, полученный в ответ в threeDSSDKKey на Шаге 10.
    • dsRoot для Android и iOS зависит от платежной системы. Скачать тестовый ключ.
12. 3DS2 SDK собирает данные устройства и шифрует их.
13. Мобильное приложение отправляет зашифрованные данные устройства на мобильный сервер.
14. Мобильный сервер инициирует второй вызов платежного API через paymentorder.do.
    • sdkEncData – зашифрованные данные устройства, которые возвращаются в методе createTransaction в 3DS2 SDK.
    • threeDSSDKReferenceNumber – официальные идентификаторы 3DS2 SDK. Не нужно их жестко кодировать. iOS: 3DS_LOA_SDK_BPBT_020100_00233, Android: 3DS_LOA_SDK_BPBT_020100_00231.
    • threeDSServerTransactionID возвращается в ответ на первый вызов платежа на Шаге 9 в параметре threeDSServerTransId.
    • sdkEphemPubKey возвращается в методе createTransaction в 3DS2 SDK.
    • sdkAppID возвращается в методе createTransaction в 3DS2 SDK.
    • sdkTransID возвращается в методе createTransaction в 3DS2 SDK.
15. Платежный шлюз возвращает новые специальные параметры для 3DS2 SDK.
16. Мобильный сервер отправляет эти параметры в мобильное приложение.
17. Мобильное приложение инициирует поток прохождения проверки с помощью метода doChallenge.
    • Параметр acsTransactionID соответствует threeDSAcsTransactionId в ответе платежного шлюза.
    • Параметр acsRefNumber соответствует параметру threeDSAcsRefNumber в ответе платежного шлюза.
    • Параметр acsSignedContent соответствует параметру threeDSAcsSignedContent в ответе платежного шлюза.
    • Параметр 3DSServerTransactionID соответствует threeDSServerTransId в ответе платежного шлюза.
18. 3DS2 SDK связывается с ACS эмитентов через CReq/CRes API до тех пор, пока клиент не подтвердит свой платеж.
19. ACS отправляет RReq платежному шлюзу для подтверждения или отклонения платежа.
20. 3DS2 SDK информирует мобильное приложение о завершении потока 3DS2 через ChallengeStatusReceiver.
21. Мобильный сервер завершает платеж с помощью finish3dsVer2Payment.do.
22. Платежный шлюз осуществляет платеж.
23. Платежный шлюз отправляет уведомление обратного вызова на сервер продавца, если оно настроено для продавца.
24. Мобильный сервер проверяет окончательный статус платежа через getOrderStatusExtended.do.
25. Мобильное приложение показывает результат платежа клиенту.

IOS

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

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

Вы можете интегрировать SDKCore.framework, добавив его вручную.

SDKCore.framework

• Скачайте последнюю версию фреймворка здесь.

• Выберите файл SDKCore.framework и добавьте его в папку проекта.

• Откройте страницу Targets -> General -> Frameworks, Libraries, and Embedded Content. Для SDKCore.framework с столбце Embed замените Do not Embed на Embed & Sign.

//ViewController.swift
...
import SDKCore
...

Работа с API V1

Внешние зависимости

Для генерации токена необходимо задать открытый ключ.

let publicKey: String =
      "-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoIITqh9xlGx4tWA+aucb0V0YuFC9aXzJb0epdioSkq3qzNdRSZIxe/dHqcbMN2SyhzvN6MRVl3xyjGAV+lwk8poD4BRW3VwPUkT8xG/P/YLzi5N8lY6ILlfw6WCtRPK5bKGGnERcX5dqL60LhOPRDSYT5NHbbp/J2eFWyLigdU9Sq7jvz9ixOLh6xD7pgNgHtnOJ3Cw0Gqy03r3+m3+CBZwrzcp7ZFs41bit7/t1nIqgx78BCTPugap88Gs+8ZjdfDvuDM+/3EwwK0UVTj0SQOv0E5KcEHENL9QQg3ujmEi+zAavulPqXH5907q21lwQeemzkTJH4o2RCCVeYO+YrQIDAQAB-----END PUBLIC KEY-----"

Метод генерации токена

let sdkCore = SdkCore()

let cardParams = CardParams(
     pan: "4111111111111111",
     cvc: "123",
     expiryMMYY: "12/28",
     cardholder: "TEST CARDHOLDER", 
     mdOrder: "mdOrder",
     pubKey: publicKey
)

let cardParamsConfig = SDKCoreConfig(
    paymentMethodParams: .cardParams(params: cardParams)
)
let tokenResult = sdkCore.generateWithConfig(config: cardParamsConfig)

let bindignParams = BindingParams(
    pubKey: publicKey,
    bindingId: "das",
    cvc: "123",
    mdOrder: "mdOrder"
)
let bindingParamsConfig = SDKCoreConfig(
    paymentMethodParams: .bindingParams(params: bindignParams)
)
let tokenResult = sdkCore.generateWithConfig(config: bindingParamsConfig)

Модели

CardParams

BindingParams

Ошибки валидации полей

Android

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

Подключение к Gradle проекту путем добавления файлов .aar библиотеки

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

build.gradle.kts

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

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

build.gradle

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

dependencies {
    // dependency is mandatory to add
    implementation(group: '', name: 'sdk_core-release', ext: 'aar')
}

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

Логирование

Внутренние процессы логируются с тегом 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)
...

Пример Kotlin_core (без графического интерфейса)

Пример формирования криптограммы

import net.payrdr.mobile.payment.sdk.core.SDKCore
import net.payrdr.mobile.payment.sdk.core.TokenResult
import net.payrdr.mobile.payment.sdk.core.model.BindingParams
import net.payrdr.mobile.payment.sdk.core.model.CardParams
import net.payrdr.mobile.payment.sdk.core.validation.BaseValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardCodeValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardExpiryValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardHolderValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardNumberValidator
import net.payrdr.mobile.payment.sdk.core.validation.OrderNumberValidator

class MainActivity : AppCompatActivity() {
    // initialization of validators for card information entry fields
    private val cardNumberValidator by lazy { CardNumberValidator(this) }
    private val cardExpiryValidator by lazy { CardExpiryValidator(this) }
    private val cardCodeValidator by lazy { CardCodeValidator(this) }
    private val cardHolderValidator by lazy { CardHolderValidator(this) }
    private val orderNumberValidator by lazy { OrderNumberValidator(this) }
    private val sdkCore by lazy { SDKCore(context = this) }

    override fun onCreate(savedInstanceState: Bundle?) {
        // installation of validators on the card information entry fields
        cardNumberInput.setupValidator(cardNumberValidator)
        cardExpiryInput.setupValidator(cardExpiryValidator)
        cardCodeInput.setupValidator(cardCodeValidator)
        cardHolderInput.setupValidator(cardHolderValidator)
        mdOrderInput.setupValidator(orderNumberValidator)

        // creation of an object and initialization of fields for a new card
        val params = NewPaymentMethodCardParams(
            pan = cardNumberInput.text.toString(),
            cvc = cardCodeInput.text.toString(),
            expiryMMYY = cardExpiryInput.text.toString(),
            cardHolder = cardHolderInput.text.toString(),
            pubKey = pubKeyInput.text.toString()
        )
        // method call to get the cryptogram for a new card
        sdkCore.generateWithConfig(SDKCoreConfig(params))

        // Creation of an object and initialization of fields for the linked card
        val params = NewPaymentMethodStoredCardParams(
            storedPaymentId = "storedPaymentMethodId",
            cvc = "123",
            pubKey = pubKeyInput.text.toString()
        )
        // method call to get the cryptogram for the linked card
        sdkCore.generateWithConfig(SDKCoreConfig(params))
    }
}

Модели

NewPaymentMethodCardParams

NewPaymentMethodStoredCardParams

TokenResult

Ошибки валидации полей

Работа с API V1

Внешние зависимости

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

val publicKey: String =
    "-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoIITqh9xlGx4tWA+aucb0V0YuFC9aXzJb0epdioSkq3qzNdRSZIxe/dHqcbMN2SyhzvN6MRVl3xyjGAV+lwk8poD4BRW3VwPUkT8xG/P/YLzi5N8lY6ILlfw6WCtRPK5bKGGnERcX5dqL60LhOPRDSYT5NHbbp/J2eFWyLigdU9Sq7jvz9ixOLh6xD7pgNgHtnOJ3Cw0Gqy03r3+m3+CBZwrzcp7ZFs41bit7/t1nIqgx78BCTPugap88Gs+8ZjdfDvuDM+/3EwwK0UVTj0SQOv0E5KcEHENL9QQg3ujmEi+zAavulPqXH5907q21lwQeemzkTJH4o2RCCVeYO+YrQIDAQAB-----END PUBLIC KEY-----"

Метод генерации токена

// TokenResult with CardParams
val cardParams: CardParams = CardParams(
    mdOrder = "mdOrder",
    pan = "4111111111111111",
    cvc = "123",
    expiryMMYY = "12/28",
    cardHolder = "TEST CARDHOLDER",
    pubKey = "publicKey"
)
val tokenResult = sdkCore.generationWithConfig(paymentCardParams = cardParams)

// TokenResult with BindingParams
val bindingParams: BindingParams = BindingParams(
    mdOrder = "mdOrder",
    bindingID = "das",
    cvc = "123",
    pubKey = "publicKey"
)

val tokenResult = sdkCore.generationWithConfig(paymentCardParams = bindingParams)