🔥Інтеграція SDK

Цей розділ містить опис методів для взаємодії додатку партнеру з SDK для реалізації flow приймання платежів. Перелік версій, та змін відокремлено у розділ Історія версій SDK

Залежності

Додайте наступні залежності до вашого build.gradle файлу:

implementation 'androidx.core:core-ktx:1.10.1'
implementation 'androidx.appcompat:appcompat:1.6.1'

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.squareup.retrofit2:converter-scalars:2.9.0'

implementation 'com.squareup.okhttp3:okhttp:4.9.3'
implementation 'com.squareup.okhttp3:logging-interceptor:4.9.3'
implementation 'com.squareup.okhttp3:okhttp-urlconnection:4.9.3'

Ініціалізація

Ви можете ініціалізувати SDK наступним чином:

Coroutines

suspend fun Defin.init(
    merchantId: String, 
    terminalId: String, 
    cashierId: String, 
    deviceId: String
) : Defin

або:

Звичайний метод

fun Defin.init(
    merchantId: String, 
    terminalId: String, 
    cashierId: String, 
    deviceId: String, 
    listener: DefinInitListener
)

Слухач має наступний формат:

object : DefinInitListener {
    override fun onSuccess(defin: Defin) {
        [email protected] = defin
    }

    override fun onFailure(error: DefinException) {
        Toast.makeText(this@MainActivity, error.getFullMessage(), Toast.LENGTH_SHORT).show()
    }
}

Оплата

Посилання на оплату буде лише у випадку оплати картою

Метод checkout використовується для створення замовлення.

Coroutines

suspend fun defin.checkout(
    paymentType: String,
    purpose: String,
    ttn: String,
    customer: DefinCustomer, // Опціонально
    goods: List<DefinGood>
) : Defin.Order

або:

Звичайний метод

fun defin.checkout(
    paymentType: String, 
    purpose: String, 
    ttn: String,
    goods: List<DefinGood>, 
    customer: DefinCustomer, // Опціонально
    listener: DefinCheckoutListener
)

де:

• paymentType // ідентифікатор виду оплати

• purpose // Призначення платежу (ТТН)

Методи оплати

Перелік доступних методів для оплати можна отримати у відповідь на ініціалізацію, а також окремим методом, якщо потрібно

defin?.availablePaymentTypes()

Існує метод отримання статусу методу оплати. Повертає true якщо переданий paymentType доступний цьому мерчанту

defin?.isAvailablePaymentType(
    paymentType: DefinPaymentType
)

Існуючі методи в системі:

DefinPaymentType — enum що містить всі можливі варианти оплати, серед них:

DefinPaymentType.CASH — Готівка

DefinPaymentType.QR — Інтернет-еквайринг (QR). Отримуємо лінку на динамічну сторінку оплати банка чи фінансової компанії

DefinPaymentType.PBT2PH — tap2phone від Приватбанку

Перелік продуктів

Перелік продуктів формується з класів DefinGood

DefinGood(
    name: String, 
    amount: Double, 
    quantity: Float,
    taxGroup: Int,
    barcode: String?,
    uktzedCode: String?
)

Для відправки чеку клієнту є класс DefinCustomer?

DefinCustomer(
    email: String, 
    phone: String, // у форматі 380991234567
)

Інтерфейс слухача оплати

DefinCheckoutListener {
    fun onSuccess(order: Defin.Order)
    fun onFailure(error: DefinException)
}

Приклад використання

launch{
    try{

        // Ініциалізаця
        val defin = Defin.init(merchantId, terminalId, cashierId, deviceId)

        // створення ордеру
        val goods = listOf(
            DefinGood(name = "Кава з молоком", amount = 2.34, quantity = 1f)
        )

        val order = defin.checkout(paymentType, purpose, ttn, goods)

    }catch(e: DefinException){
        Log.e("Defin", e.getFullMessage())
    }
}

// Або

private lateinit var defin: Defin

// Ініциалізаця
Defin.init(merchantId, terminalId, cashierId, deviceId, object : DefinInitListener{
    override fun onSuccess(defin: Defin) {
        [email protected] = defin
    }

    override fun onFailure(error: DefinException) {
        Toast.makeText(this@MainActivity, error.getFullMessage(), Toast.LENGTH_SHORT).show()
    }
})

// створення ордеру

val goods = listOf(
    DefinGood(name = "Кава з молоком", amount = 2.34, quantity = 1f)
)

fun defin.checkout(paymentType, purpose, ttn, goods, object : DefinCheckoutListener {
    override fun onSuccess(order: Defin.Order) {
        // Ваш код
    }
    override fun onFailure(error: DefinException) {
        // Обробка помилки
    }
})

Варіанти оплати

На поточний момент реалізовано три методи оплати (готівка, інвойсинг та tap2phone)

• У випадку оплати готівкою, зарахування виконується одразу;

• Для сплати через банківську форму, слід використати order.paymentUrl;

• Для можливості сплати через tap2phone, використовуйте наступну реалізацію:

tap2phone

1. Для того щоб мати можливість виклику зовнішнього додатку програмного терміналу, ініціалізуйте клас на рівні активності:

private val tapToPhone = TapToPhone(this)

1. Реалізуйте виклик терміналу в методі onSuccess(order: Defin.Order):

tapToPhone.pay(order, object : TapToPhone.Callback{
    override fun onSuccess() {
        PaymentDialog(this@MainActivity, 
            order).show()
    }
    override fun onFailure(error: DefinException) {
        Toast.makeText(this@MainActivity, 
            error.message, 
            Toast.LENGTH_SHORT).show()
    }
})

Перевірка статусу оплати

Для отримання інформації про плату, використовуйте метод order.check з інтерфейсом DefinCheckListener.

Інтерфейс DefinCheckListener

DefinCheckListener{
    fun onSuccess(status: GoodsStatus)
    fun onFailure(error: DefinException)
}

Приклад використання

suspend fun order.check() : GoodsStatus

// або

fun order.check(object : DefinCheckListener{
    override fun onSuccess(status: GoodsStatus) {
        // Ваш код
    }
    override fun onFailure(error: DefinException) {
        // Обробка помилки
    }
})

Варіанти status:GoodsStatus

• DRAFT // Драфтове замовлення

• CREATED // Замовлення очікує оплати

• COMPLETED // Замовлення завершено

• FAILED // Помилка

Отримання чеку

В order: Defin.Order присутній метод receipt, який приймає обʼєкт, реалізуючий інтерфейс DefinReceiptListener.

Інтерфейс DefinReceiptListener

suspend fun receipt(): DefinReceipt

// або

fun order.receipt(object : DefinReceiptListener{
    override fun onSuccess(receipt: DefinReceipt) {
        // Ваш код
    }
    override fun onFailure(error: DefinException) {
        // Обробка помилки
    }
})

Метод перевірки статусу та отримання квитанції (відокремлено від DefinOrder)

Перевірка статусу оплати

suspend fun getStatusByPaymentId(paymentId: String): Statuses
//або 

fun getStatusByPaymentId(paymentId: String, listener: DefinCheckListener)

Отримати квитанцію

suspend fun getReceiptByPaymentId(paymentId: String): DefinReceipt
//або 

fun getReceiptByPaymentId(paymentId: String, listener: DefinReceiptListener)