Оплата за допомогою додатку "Термінал"

З питань отримання ідентифікаторів зовнішніх сервісів, ключів для підпису, та адреси сервісу перевірки платежів звертатися:

Галушкін Максим Сергійович

E-mail: maksim.galushkin@privatbank.ua

1. Підготовка параметрів та підпис даних запитів

2. Сервіс токенізації операцій

3. Виклик додатку "Термінал" для виконання операції (Android)

4. Виклик додатку "Термінал" для виконання операції ( iOS )

5. Сервіс отримання інформації щодо операції

6. Опис  реверсу

7. Коди відповідей

1.Підготовка параметрів та підпис даних запитів

Для правильного формування запиту на любой з сервісів ( token.php чи check.php) потрібно до скрипта додвати параметри clid, signed, signature

    url = {https://dio.privatbank.ua}
    * - запит token/check
    POST {url}/api/nfcpos/integrators/*.php?clid=test&signed=1476193110
    &signature=2b3a694f0fe2574bd85edb0f5e723af013c089d9

Параметр signature розраховується за формулою:

sha1( signed + secret + data + secret )

де:

secret - ключ для підпису, видається разом з ідентифікатором зовнішнього сервісу data - вміст тіла запиту

Параметри clid, signed, signature завжди передаються всередині url.

Приклад запиту

clid = test
secret = test
signed = 1697051765  (Wed Oct 11 2023 19:16:05 GMT+0000)
data =  {"operation" : "pay" ,"amount":1.0, "purpose" : "test"}

POST https://dio.privatbank.ua/api/nfcpos/integrators/token.php?clid=test
&signed=1697051765&signature=0c19f9efae8ce89efb542bd52c88954a99496126 

Content-Type: application/json
тіло запиту
{"operation" : "pay" ,"amount":1.0, "purpose" : "test"}

PHP приклад формування і підпісу праметрів запіту отрімання токену для операції Оплата

$clid = 'test';  
$secret = 'abcdef';  
//для тестування та перевірки
//в реальных запросах должно быть текущее в время серверв UTC в секундах 
$signed = '1624023225'; // (для UTC 2021-06-18 13:33:45 +0000)

/*** 
Pay     
Під час формування підпису в $data необхідно враховувати саме той набір
 параметрів, який буде передано в тілі запиту. Тобто, якщо запит містить
 необов'язкові поля, під час формування підпису потрібно використовувати
 всі поля, які фактично присутні в запиті. 
*/
$params = array(
    'operation' =>  'pay',
    'amount' =>  3.33,
    'purpose' =>  'Test'
);

$data = json_encode($params);

//формирование подписи sha1( signed + secret + data + secret )
$signature = sha1( $signed . $secret . $data . $secret );
//значення після обчислення для перевірки
// signature=896e7808ed56bde0e3966b46b30688e0715bb439

$url = 'https://dio.privatbank.ua/api/nfcpos/integrators/token.php?clid='
.$clid  . '&signed=' . $signed . '&signature=' . $signature;

$options = array( CURLOPT_HTTPHEADER => array( 'Content-Type' => 'application/json' ));

2.Сервіс токенізації операцій

Для взаємодії з платіжним застосунок Термінал та виконання фінансових операцій оплата/повернення необхідно використовувати API для отримання токенів. Залежно від типу виконуваної операції необхідно підготувати та передати у запиті відповідні параметри.

Коли клієнт надає агрегатору токен, то  агрегатор має додати  до  тіла  запита  ще  один  параметр, під назвою "client_token".

Якщо в запиті на токенізацію вказано phone та retailer_id, і цей термінал доступний у застосунку, то термінал буде обрано автоматично.

Запит на отримання токену:

POST https://dio.privatbank.ua/api/nfcpos/integrators/token.php? clid= {ID компанії яка створює токен}&signed={ключ}&signature={значення хешу}

Параметри тіла запитів:

    Оплата

{
  "operation": "pay",
  " amount": 3.33,
  "purpose": "Test",
  "client_token": "zgvIgAQ5jbXIsvDrAahW7MVKNXk7Tq1114SnG9UKYtyXTNZJD437xwmAnk4IYUyN"
}

     Повернення

{
  "operation": "refund",
  " amount": 3.33,
  "transaction_id": "Test",
  "client_token": "zgvIgAQ5jbXIsvDrAahW7MVKNXk7Tq1114SnG9UKYtyXTNZJD437xwmAnk4IYUyN"
}

Формат вхідних параметрів

Успішна відповідь

{
 "success": true,
 "rid": "b3e195e0eba6d921a95231cd78937d6a",
 "jwt": "ey******kzMzZkOVGVzdCJ9.x-qLonr823cU2NK0ETJ1gaaUpmJ-WXov0",
 "status": 200
}

Опис Вихідних параметрів

3.Виклик додатку "Термінал" для здійснення оплати (Android)

Після успішного отримання токена для фінансової операції.

Приклад виклику та передачі параметрів

val jwtToken:String = "*****"   //JWT токен операциії (П. 1)
val callback = "https://******" //callback

startTerminalApp(jwtToken: String, callback:String)

Формат параметрів

Функція виклику додатку

const val DEEP_LINK_URL = "nfcterminal://executor"

private fun startTerminalApp(jwtToken: String, callback:String) {
        val launchIntent =
            packageManager.getLaunchIntentForPackage("ua.privatbank.pterminal")
        if (launchIntent != null) {
            val intent = Intent(Intent.ACTION_VIEW)
            val jwtTokenEncode = URLEncoder.encode(jwtToken, "utf-8")
            intent.data = Uri.parse(DEEP_LINK_URL+"?token=$jwtTokenEncode&callback=$callback")
            try {
                startTerminalForResult.launch(intent)
            } catch (e: Exception) {
                e.printStackTrace()
            }

        } else {
            try {
                startActivity(
                    Intent(
                        Intent.ACTION_VIEW,
                        Uri.parse("market://details?id=ua.privatbank.pterminal")
                    )
                )
            } catch (e: android.content.ActivityNotFoundException) {
                try {
                    startActivity(
                        Intent(
                            Intent.ACTION_VIEW,
                            Uri.parse("https://play.google.com/store/apps/details?id=ua.privatbank.pterminal")
                        )
                    )
                } catch (e: Exception) {
                    e.printStackTrace()
                }
            }
        }
    }

Отримання та обробка результату

private val startTerminalForResult =
  registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
      if (result.resultCode == AppCompatActivity.RESULT_OK) {
          val intent = result.data
          if (intent != null) {
              val tresult = intent.getStringExtra("result") //результат виконання операції
              Log.d(TAG,"Intent Transaction result = $tresult")
              binding.edResult.setText(tresult)
          } else {
              Log.d(TAG,"intent == NULL")
          }
      } else {
          Log.d(TAG, "result != RESULT_OK")
      }
  }

Результат виконання операції повертається у форматі JSON

Формат відповіді

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbG*******",
  "date": "2022-07-13 16:30:50",
  "error": "",
  "operation_id": "PAX62cec9140b7052.60786725",
  "result": true
}

4.Виклик додатку "Термінал" для здійснення оплати (iOS)

Після успішного отримання токена для фінансової операції.

Приклад виклику та передачі параметрів:

let jwtToken = "*****"  // JWT токен операциії (П. 1)
let callback = "https://******/?id=unique_identifier" // буде виклакано по завершеню операції, id=unique_identifier як приклад ідентифікації операції  

let terminalUrlScheme = "nfcterminal://executor"

let urlString = terminalUrlScheme + "?token=\(jwtToken)&callback=\(callbackUrl)"

if let url = URL(string: urlString) {
    UIApplication.shared.open(url)
}

Формат параметрів

Для обробки виклику callback, застосунок може бути налаштовано одним із способів:

• universal links, наприклад "https://my.app.site/callback/result/?id=unique_identifier" Apple документація
• url scheme, наприклад "myappcallback://result?id=unique_identifier" Apple документація

Отримання та обробка результату відбуваєтся через Сервіс отримання інформації щодо операції

5.Сервіс отримання інформації щодо операції

Використовується для отримання результату операції, зробленої за допомогою додатку "Термінал"

POST [https://dio.privatbank.ua/api/nfcpos/integrators/check.php?**clid=**{ID клієнта}&signed={ключ}&signature={значення хешу}

Параметри операції

*jwt *- токен, отриманий для виконання операції

{
 "jwt": "ey******kzMzZkOVGVzdCJ9.x-qLonr823cU2NK0ETJ1gaaUpmJ-WXov0"
}

Успішна відповідь для операції Оплата

{
  "success": true,
  "rid": "addc2a61a4d0d23abbdf09bf24b46bdd",
  "pay": {
    "code": "iso00_Approved",
    "user_message": "Успішно",
    "merchant": "M11302GG",
    "traceId": "0471edb9526efc43ad9e680c2dec0ee5",
    "approval_code": "131192",
    "processing_code": "000000",
    "response_code": "00",
    "rrn": "014722766522",
    "batch_id": 0,
    "discount_amount": 0,
    "discount_percent": 0,
    "discount_type": "no_discount",
    "amount_full": 3.33,
    "payment_system": "Visa",
    "masked_pan": "4149********1451",
    "qr_code": "",
    "receipt": "HTML чек ",
    "receipt_id": 0,
    "date": "20230705 08:20:09 +0000",
    "stan": "082597",
    "transaction_id": "PAX-TEST-64a527b82b7479.87095729"
  },
  "status": 200
}

Успішна відповідь для операції Повернення

{
  "success": true,
  "rid": "a60a7953e5678664398f15755b12410f",
  "pay": {
    "code": "iso00_Approved",
    "user_message": "Успішно",
    "merchant": "M11302GG",
    "traceId": "0471edb9526efc43ad9e680c2dec0ee5",
    "approval_code": "131192",
    "processing_code": "000000",
    "response_code": "00",
    "rrn": "014722766522",
    "batch_id": 0,
    "discount_amount": 0,
    "discount_percent": 0,
    "discount_type": "no_discount",
    "amount_full": 3.33,
    "payment_system": "Visa",
    "masked_pan": "4149********1451",
    "qr_code": "",
    "receipt": "HTML чек",
    "receipt_id": 0,
    "date": "20230705 08:20:09 +0000",
    "stan": "082597",
    "transaction_id": "PAX-TEST-64a527b82b7479.87095729"
  },
  "refunds": [
    {
      "amount": 3.33,
      "state": 1,
      "date": "2023-07-05T11:27:56.522626"
    }
  ],
  "status": 200
}

Успішна відповідь для операції Реверс

 {
  "success": true,
  "rid": "63f86ba5fd078c104afd9a86ba29df96",
  "pay": {
    "code": "iso00_Approved",
    "user_message": "Успішно",
    "merchant": "M11302EP",
    "approval_code": "900060",
    "processing_code": "000000",
    "response_code": "00",
    "rrn": "014724824026",
    "amount_full": 100,
    "payment_system": "Visa",
    "masked_pan": "4731********1548",
    "receipt": "    <div class=\"pb-receipt receipt\">\n            <div class=\"pb-logo\"> </div>\n    <div class=\"r-header\">\n            <p>Silpo Тестовий  мерчант (M11302EP)</p>\n    <p>область Дніпропетровська,район Дніпровський,місто Дніпро,вулиця Архітектора Заболотного,будинок 1</p>\n    <p>ЄДРПОУ/ІПН 31435622</p>\n    <p>'TEST TEST MCB'</p>\n    </div>\n    <div class=\"font-xl font-bold hl\">Оплата</div>\n\n    <div class=\"block i-block\">\n            <div class=\"flex-line \">\n        <p>Телефон підтримки</p>\n        <p>3700</p>\n    </div>\n    <div class=\"flex-line \">\n        <p>Сайт АТ КБ ПриватБанк</p>\n        <p>www.privatbank.ua</p>\n    </div>\n    </div>    <hr class=\"dot-line\">\n\n    <div class=\"block main-block\">\n            <div class=\"flex-line \">\n        <p>VISA</p>\n        <p>4731********1548</p>\n    </div>\n    <div class=\"flex-line font-n font-bold\">\n        <p>СУМА</p>\n        <p>100,00 грн</p>\n    </div>\n    </div>    <hr class=\"dot-line\">\n    <div class=\"block i-block\">\n            <p>Підпис клієнта не потрібен</p>\n    <p>Мерчант: M11302EP</p>\n    <p>Код авторизації: 900060</p>\n    <p>AID: A0000000031010</p>\n    <p>RRN: 014724824026</p>\n    <p>27.01.2025 16:39:11</p>\n    </div>\n    </div>                       ",
    "date": "20250127 14:39:11 +0000",
    "stan": "098801",
    "batch_id": 0,
    "discount_amount": 0,
    "discount_percent": 0,
    "discount_type": "no_discount",
    "qr_code": "",
    "receipt_id": 0,
    "transaction_id": "PAX-TEST-67979a8e722d30.66656501"
  },
  "reverses": [
    {
      "amount": 100,
      "id": 1901,
      "created": "2025-01-27 16:39:57",
      "updated": "2025-01-27 16:39:58",
      "reversed": null,
      "state": 0,
      "state_description": "InProgress"
    },
    {
      "amount": 100,
      "id": 1903,
      "created": "2025-01-28 11:31:24",
      "updated": "2025-01-28 11:31:24",
      "reversed": null,
      "state": 0,
      "state_description": "InProgress"
    },
    {
      "amount": 100,
      "id": 1939,
      "created": "2025-01-31 15:29:39",
      "updated": "2025-01-31 15:29:39",
      "reversed": null,
      "state": 2,
      "state_description": "Failed"
    }
  ],
  "status": 200

Опис вихідних параметрів

6.Опис  реверсу

Використовується для для  формування реверсу операції, яка  буде  передана  у запиті.

POST [https://dio.privatbank.ua/api/nfcpos/integrators/reverse.php?clid={ID клієнта}&signed={ключ}&signature={значення хешу} .

Параметри операції:

transaction_id -  ідентифікатор  транзакції по якій намагаємось провести реверс. Приклад:

{
  "transaction_id": "PAX-TEST-67977ccf9d76d8.61511107"
}

Відповідь:

id - Ідентифікатор заявки на реверс , int

result - Результат виконання операції, string (TransactionResult) (Enum: "ok" "error" "retry")

code - Код виконання операції реверсу, string, 

user_message - Текстове повідомлення клієнту при помилці

merchant - Мерчант користувача

response_code - Код відповіді авторизацій ПЦ

date - Дата виконання транзакції у  форматі 20231103 17:40:50 +0000

status - статус  відповіді  200 - ОК 

{
  "success": true,
  "rid": "ebb621d7a87dfbe9524a0cb3b158aee4",
  "id": 1944,
  "result": "ok",
  "code": "guaranteeOffline",
  "user_message": null,
  "merchant": "M123456",
  "response_code": "00",
  "date": "20250206 20:32:05 +0000",
  "status": 200
}

Таблиця  з результатами  та кодами виконання операції

7.Коди відповідей

Приклад відповіді з помилкою

{
 "success": false,
 "rid": "ce2f4a3454c35a6429adfd7a67f35ddc",
 "status": 400,
 "message" : "Невалідні дані запиту.",
 "error" : "IE_01"
}