Android SDK (Android, kotlin)

SDK Android - это библиотека позволяющая упростить взаимодействие с API. Система SDK работает на Android 4.4 и выше.

Описание возможностей:

Инициализация платежа
Отмена платежа
Возврат платежа
Проведение клиринга
Проведение рекуррентного платежа с сохраненными картами
Получение информации/статуса платежа
Добавление карт/Удаление карт
Оплата добавленными картами
Безакцептные платежи
Создание платежа с Google Pay

Установка:

1. Добавьте репозитории Jitpack в ваш build.gradle на уровне проекта в конец репозиториев allprojects:

allprojects {
    repositories {
        // ...
        maven { url "https://jitpack.io" }
    }
}

2. Добавьте в ваш build.gradle:

dependencies {
	implementation 'com.github.PayBox:kotlin-paybox-sdk:0.11.0'
}

Для связи с SDK

1. Инициализация SDK:

	var sdk = PayboxSdk.initialize(merchantID, "secretKey")

2. Добавьте PaymentView в ваше activity:

	<money.paybox.payboxsdk.view.PaymentView
           android:id="@+id/paymentView"
           android:layout_width="match_parent"
           android:layout_height="match_parent"/>

3. Передайте экземпляр paymentView в sdk:

	sdk.setPaymentView(paymentView)

4. Для отслеживания прогресса загрузки платежной страницы используйте WebListener:

    paymentView.listener = this
        
    override fun onLoadStarted() {
                
    }
    
    override fun onLoadFinished() {
                
    }

Настройки SDK

Тестовый режим:

    sdk.config().testMode(enabled)  //По умолчанию тестовый режим включен

Выбор региона:

    sdk.config().setRegion(Region.DEAFAULT) //Region.DEAFAULT по умолчанию

Класс Region имеет следующие значения:

Выбор платежной системы:

    sdk.config().setPaymentSystem(paymentSystem)

Выбор валюты платежа:

    sdk.config().setCurrencyCode(code)

Активация автоклиринга:

    sdk.config().autoClearing(enabled)

Установка кодировки:

    sdk.config().setEncoding(encoding) //по умолчанию UTF-8

Время жизни рекурентного профиля:

    sdk.config().setRecurringLifetime(lifetime) //по умолчанию 36 месяцев

Время жизни платежной страницы, в течение которого платеж должен быть завершен:

    sdk.config().setPaymentLifetime(lifetime)  //по умолчанию 300 секунд

Включение режима рекурентного платежа:

    sdk.config().recurringMode(enabled)  //по умолчанию отключен

Номер телефона клиента, будет отображаться на платежной странице. Если не указать, то будет предложено ввести на платежной странице:

    sdk.config().setUserPhone(userPhone)

Email клиента, будет отображаться на платежной странице. Если не указать email, то будет предложено
ввести на платежной странице:

    sdk.config().setUserEmail(userEmail)

Язык платежной страницы:

    sdk.config().setLanguage(language)

Для передачи информации от платежного гейта:

    sdk.config().setCheckUrl(url)
    sdk.config().setResultUrl(url)
    sdk.config().setRefundUrl(url)
    sdk.config().setClearingUrl(url)
    sdk.config().setRequestMethod(requestMethod)

Для выбора Frame вместо платежной страницы:

    sdk.config().setFrameRequired(true) //false по умолчанию

Работа с SDK

Создание платежа:

    sdk.createPayment(amount, "description", "orderId", userId, extraParams) {
            payment, error ->   //Вызовется после оплаты
    }

После вызова в paymentView откроется платежная страница

Рекурентный платеж:

   sdk.createRecurringPayment(amount,"description","recurringProfile", "orderId") {
            recurringPayment, error -> //Вызовется после оплаты
   }

Получение статуса платежа:

   sdk.getPaymentStatus(paymentId) {
            status, error ->  // Вызовется после получения ответа
   }

Клиринг платежа:

   sdk.makeClearingPayment(paymentId, amount) {     // Если указать null вместо суммы клиринга, то клиринг пройдет на всю сумму платежа
            capture, error -> // Вызовется после клиринга
   }

Отмена платежа:

   sdk.makeCancelPayment(paymentId) {
            payment, error -> //Вызовется после отмены
   }

Возврат платежа:

   sdk.makeRevokePayment(paymentId, amount) {
            payment, error -> //Вызовется после возврата
   }

Сохранение карты:

   sdk.addNewCard(userId,"postLink") {
            payment, error -> // Вызовется после добавления
   }

После вызова в paymentView откроется платежная страница

Получить список сохраненых карт:

   sdk.getAddedCards(userId){
            cards, error -> // Вызовется после получения ответа
   }

Удаление сохраненой карты:

   sdk.removeAddedCard(cardId, userId) {
            card, error ->  // Вызовется после получения ответа
   }

Создание платежа сохраненой картой:

   sdk.createCardPayment(amount, userId, "cardToken", "description", "orderId"){
            payment, error -> // Вызовется после создания
   }

Внимание: Метод createCardPayment с использованием cardID является устаревшим.

Для оплаты созданного платежа:

   sdk.payByCard(paymentId){
            payment, error -> //Вызовется после оплаты
   }

После вызова в paymentView откроется платежная страница для 3ds аутентификации

Для оплаты созданного платежа c безакцепным списанием:

   sdk.createNonAcceptancePayment(paymentId, merchantId){
            payment, error -> //Вызовется после оплаты
   }

Интеграция Google Pay

1. Добавьте в ваш build.gradle:

   implementation 'com.google.android.gms:play-services-wallet:19.2.1'

2. Далее следует обновить AndroidManifest:

   <application>
   ...
   <!-- Enables the Google Pay API -->
   <meta-data
       android:name="com.google.android.gms.wallet.api.enabled"
       android:value="true" />
   </application>

3. Добавьте PayButton в ваше xml:

<com.google.android.gms.wallet.button.PayButton
       android:id="@+id/buttonPaymentByGoogle"
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       />

4. Инициализация кнопки для оплаты с Google Pay PayButton:

      val googlePayButton: PayButton = findViewById(R.id.buttonPaymentByGoogle)
         googlePayButton.initialize(
            ButtonOptions.newBuilder()
                .setButtonType(ButtonType.CHECKOUT)
                .setButtonTheme(ButtonTheme.LIGHT)
                .build()
        )

5. Инициализация PaymentsClient:

	 val googlePaymentsClient = Wallet.getPaymentsClient(
            this,
            Wallet.WalletOptions.Builder()
                .setEnvironment(WalletConstants.ENVIRONMENT_PRODUCTION)
                .setTheme(WalletConstants.THEME_LIGHT)
                .build()
        )

Подробнее: Wallet.getPaymentsClient- метод, для получения экземпляра PaymentsClient.

Параметры методов

6. Создание платежа с использованием Google Pay:

     // Повесим на кнопку обработчик нажатий
     googlePayButton.setOnClickListener {
     
     // Создание платежа с использованием Google Pay
     sdk.createGooglePayment(amount, description, orderId, userId, extraParams) 
     { payment, error -> // Вызывается после создания
     
       // Получаем url для подтверждения платежа
       url = payment?.redirectUrl.toString()
       
       // Инициирует загрузку данных платежа с использованием Google Pay
       AutoResolveHelper.resolveTask<PaymentData>(
                    googlePaymentsClient.loadPaymentData(createPaymentDataRequest()),
                    this,
                    REQUEST_CODE
                )
         }
      }
     
       companion object {
        // Код запроса, который будет использоваться при вызове
             const val REQUEST_CODE = 123
       }

Подробнее:

sdk.createGooglePayment— cоздание платежа с использованием Google Pay

createPaymentDataRequest() — метод, который возвращает объект PaymentDataRequest. Этот объект определяет параметры и требования для запроса данных платежа, таких как методы оплаты, адрес доставки и др. (ниже приведен код)

loadPaymentData() — инициирует асинхронную задачу для загрузки данных платежа с использованием предоставленного запроса.

AutoResolveHelper.resolveTask<PaymentData>()— метод, используется для обработки задачи загрузки данных платежа.

REQUEST_CODE— код запроса, который будет использоваться для идентификации результата задачи в методе onActivityResult.

7. Метод createPaymentDataRequest() — создает и возвращает запрос PaymentDataRequest для использования с Google Pay API:

     private fun createPaymentDataRequest(): PaymentDataRequest {
     
    // Создание нового строителя запроса
    val request = PaymentDataRequest.newBuilder()
    
        // Установка информации о транзакции
        .setTransactionInfo(
            TransactionInfo.newBuilder()
            
                // Статус окончательной цены
                .setTotalPriceStatus(WalletConstants.TOTAL_PRICE_STATUS_FINAL)
                
                // Общая сумма платежа
                .setTotalPrice("12.00")
                
                // Код валюты (например, "KZT")
                .setCurrencyCode("KZT")
                
                .build()
        )
        
        // Разрешение оплаты банковской картой
        .addAllowedPaymentMethod(WalletConstants.PAYMENT_METHOD_CARD)
        
        // Разрешение оплаты токенизированной банковской картой
        .addAllowedPaymentMethod(WalletConstants.PAYMENT_METHOD_TOKENIZED_CARD)
        
        // Установка требований к банковской карте
        .setCardRequirements(
            CardRequirements.newBuilder()
                // Разрешенные сети карт
                .addAllowedCardNetworks(
                    Arrays.asList(
                        WalletConstants.CARD_NETWORK_VISA,
                        WalletConstants.CARD_NETWORK_MASTERCARD
                    )
                )
                .build()
        )
    
    // Настройка параметров токенизации метода оплаты
    val params = PaymentMethodTokenizationParameters.newBuilder()
    
        // Тип токенизации (в данном случае - платежный шлюз)
        .setPaymentMethodTokenizationType(
            WalletConstants.PAYMENT_METHOD_TOKENIZATION_TYPE_PAYMENT_GATEWAY
        )
        
        // Параметры для платежного шлюза (например, "gateway", "gatewayMerchantId")
        .addParameter("gateway", "yourGateway")
        .addParameter("gatewayMerchantId", "yourMerchantIdGivenFromYourGateway")
        .build()
    
    // Установка параметров токенизации в запрос
    request.setPaymentMethodTokenizationParameters(params)
    
    // Возвращение построенного запроса
    return request.build()
   }

Подробнее:

PaymentDataRequest.newBuilder() - создает новый строитель запроса данных платежа.

setTransactionInfo()- устанавливает информацию о транзакции, такую как общая сумма платежа и код валюты.

PaymentMethodTokenizationParameters.newBuilder() - создает строитель параметров токенизации метода оплаты.

setPaymentMethodTokenizationType() - устанавливает тип токенизации (в данном случае - платежный шлюз).

addParameter()- добавляет параметры для платежного шлюза, такие как "gateway" и "gatewayMerchantId".

setPaymentMethodTokenizationParameters()- устанавливает параметры токенизации в запрос данных платежа.

8. Получаем результат в onActivityResult():

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        when (requestCode) {
            REQUEST_CODE -> {
                when (resultCode) {
                    Activity.RESULT_OK -> {
                       if (data == null)
                            return
                        val paymentData = PaymentData.getFromIntent(data)
                        val token = paymentData?.paymentMethodToken?.token ?: return
                        
                        // После получения токена мы подтверждаем платеж, отправляя запрос на ранее полученный URL. 
                        // Описано в пункте №9               
                        sdk.confirmGooglePayment(url, token) { payment, error ->
                        }
                    }
                    AutoResolveHelper.RESULT_ERROR -> {
                        if (data == null)
                            return
                        val status = AutoResolveHelper.getStatusFromIntent(data)
                      
                    }
                    else -> {}
                }
            }
            else -> {}
        }
    }

Подробнее:

onActivityResult - используется для обработки результатов, возвращаемых активностью интеграции с Google Pay.

data - объект , содержащий данные, возвращенные активностью.

Activity.RESULT_OK - это константа, указывает на успешное завершение операции

AutoResolveHelper.RESULT_ERROR - это константа,используемая для указания, что произошла ошибка при разрешении запроса.

9. Подтверждение платежа:

 sdk.confirmGooglePayment(url, token) { payment, error -> }