УКР | [ENG](https://hackmd.io/oG7Wt7PLQS2R8MViKAsm-Q)
:arrow_left: [На Головну](/eSq3juGWQLS1wVvJZiTUAQ)

# [40015] Отримання посилання віджета для проходження ідентифікації "BankID/Дія"

## Застосування

Запити [40015] застосовуються для отримання посилання віджета для проходження ідентифікації "[BankID](https://uk.wikipedia.org/wiki/BankID)" або "[Дія](https://uk.wikipedia.org/wiki/%D0%94%D1%96%D1%8F_(%D1%81%D0%B5%D1%80%D0%B2%D1%96%D1%81))".


## Запит

*Опис атрибутів "Partner", "KeyAES" та "Sign" див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA).*

### Структура "Data"

Структура "Data" для запитів [10015/10025/10035/10045] однакова та формується з наступних параметрів:

:::info
<details>
<summary>Формування структури "Data" (приклади наведені нижче)</summary>
<br>

~~~
{
"UserID": "",
"Phone": "",
"Email": "",
"FirstName": "",
"LastName": "",
"MiddleName": "",
"RedirectURL": "",
"CallbackURL": "",
"Transaction": {
"TransactionID": "",
"TerminalID": "",
"DateTime": ""
}
}
~~~
</details>
:::

| Параметр | Обов'яз-ковість | Тип | Опис |Приклад|
|:----:|:----:|:----:|----|:----:|
|`UserID`|Ні |Рядок|Унікальний ідентифікатор клієнта у системі Партнера.|`Uwuh0B5GQVuokYSL`|
| `Phone` | Так | Рядок | Телефон клієнта у форматі: "380ххххххххх". |`380679335544`|
| `Email` | Ні | Рядок | Email клієнта. |`[e-mail]`|
| `FirstName` | Ні | Рядок | Ім'я клієнта. |`Олег`|
| `MiddleName` | Ні | Рядок | По батькові клієнта. |`Михайлович`|
| `LastName` | Ні | Рядок | Прізвище клієнта. |`Подільський`|
| `RedirectURL` | Ні | Рядок | URL адреса сторінки, на яку буде перенаправлений клієнт після проходження процедури ідентифікації.| `https://partner.com/result_page`|
| `CallbackURL` | Так | Рядок | URL адреса сторінки, на яку буде відправлено сallback із статусом ідентифікації після проходження процедури ідентифікації.| `https://partner.com/callback/xpass`|
|`Transaction`|Так|Структура|Структура, що передає дані про транзакцію. Див. розділ ["Структура "Transaction"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA#2-Data).|Див. нижче.|

:::success
<details>
<summary>Приклад запиту [40015]</summary>
<br>

~~~md
{
"Partner": {
"PartnerToken": "c6b218dc-e95c-4190-8850-960246eaab18",
"OperationType": 40015
},
"Data": "{\"Email\": \"[e-mail]\", \"Phone\": \"380979011321\", \"LastName\": \"Подільський\", \"FirstName\": \"Олег\", \"MiddleName\": \"Михайлович\", \"CallbackURL\": \"https://partner.com/callback/xpass\", \"Transaction\": {\"TransactionID\": \"identity.e9e6e67e-7ddb-11ec-a42c-926b407ba61b\"}}",
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

## Відповідь

*Загальна інформація по формуванню структури відповіді наведена у розділі [“Загальна інформація по підключенню (API)”](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA?both#%D0%A1%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%B2%D1%96%D0%B4%D0%BF%D0%BE%D0%B2%D1%96%D0%B4%D1%96).*

### Структура "Data"

Успішна відповідь на запити [40015] містить посилання у вигляді рядка з назвою `URI` у структурі "Data":

| Параметр | Обов’яз-ковість | Тип | Опис | Приклад |
|:-:|:-:|:-:|-|:-:|
| `URI` |Так| Рядок | Посилання на віджет "BankID/Дія". |`https://stage-mapi.xpay.com.ua/uk/frame/widget/bank-id/691fafc9-5d64-46b5-22ba-85ce61cc26be`|
|`uuid`|Так|Рядок|Унікальний ідентифікатор платіжного інструменту, що зв’язує запити віджету. |`f3cd72b6-e1ea-406f-9b44-a9b93b401b7f`|

### Приклади відповідей

:::success
<details>
<summary>Операція проведена успішно</summary>
<br>

~~~md
{
"Code": 200,
"Message": "done!",
"Data": {
"OperationDate": "2022-01-17T16:32:04.673105+02:00",
"OperationID": 8122388,
"OperationStatus": 10,
"URI": "https://stage-mapi.xpay.com.ua/uk/frame/widget/bank-id/691fafc9-5d64-46b5-22ba-85ce61cc26be",
"uuid": "691fafc9-5d64-46b5-22ba-85ce61cc26be"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

:::success
<details>
<summary>Помилка виконання операції - "Користувача не знайдено"</summary>
<br>

~~~md
{
"Code": 200,
"Message": "User not found",
"Data": {
"Reason": "UNF",
"OperationStatus": 21,
"DateTime": "20180510 13:23:19"
},
"KeyAES": "",
"Sign": ""
}
~~~
</details>
:::

## GET запит

Далі необхідно відкрити сторінку, отриману в структурі відповіді, клієнту: «URI».
Після завершення процедури ідентифікації на адресу з параметра «CallbackURL» буде надіслано GET-запит з наступними параметрами:

| Параметр | Обов’яз-ковість | Тип | Опис |Приклад |
|:-:|:-:|:-:|-|:-:|
| `command` | Так | Рядок | Тип запиту: </br> - "success" - у разі успіху, </br> - "error" - у разі помилки. | `success` або `error` |
| `operation_id` | Так | Рядок | Унікальний ідентифікатор операції в системі Оператора. | `37500` |
| `txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції в системі Оператора. | `321455` |
| `partner_txn_id` | Так | Рядок | Унікальний ідентифікатор транзакції в системі Партнера, надісланий у запиті [40015]. | `453135c6e2` |
|`uuid`|Так|Рядок|Унікальний ідентифікатор, що зв’язує запити віджету. |`f3cd72b6-e1ea-406f-9b44-a9b93b401b7f`|
| `аccount` | Так | Рядок | Унікальний ідентифікатор клієнта у системі Партнера: телефон або email. | `380638754213` |
| `txn_date` |Так|Рядок| Дата та час проведення операції. Формат: YYYYMMDD_HHMMSS.| `20190301_180233` |
| `sign` |Ні|Рядок| Підпис сформований за допомогою приватного ключа з [конкатенації](https://uk.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D0%BA%D0%B0%D1%82%D0%B5%D0%BD%D0%B0%D1%86%D1%96%D1%8F) рядків даних: </br> `command`+`operation_id`+ `txn_date`+`account`+ `txn_id`+`partner_txn_id`. </br> Алгоритм формування підпису див. у розділі ["Загальна інформація по підключенню (API)"](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA). |`uDzPcuDjEFlC2FG-2Mjr566GKGIArfK-kcIA3LYTcXmavB3-9QBGmlVyU2yXG64-TM4qDq2kMBxXOQR-ueBMDcYgYkycyTd-Y8Q%3D%3D`|

:::success
<details>
<summary>Приклад формування рядка для підпису "sign"</summary>
<br>
Дані запиту:

~~~md
command=success
operation_id=37500
txn_date=20190301_180233
account=380638754213
txn_id=321456
partner_txn_id=453135c6e2
~~~
Рядок для підпису:
~~~md
success3750020190301_180233380638754213321456453135c6e2
~~~
</details>
:::

## Довідкові матеріали

Опис загальних параметрів системи XPAY див. у розділі ["Довідкові матеріали"](https://hackmd.io/aBE7H5cfQ-iqaN3SnwaQ-w): коди типів операцій, типи платіжних методів, коди статусів обробки операцій, відомості та помилки, що повертаються у відповіді та ін.

:arrow_left: [На Головну](/eSq3juGWQLS1wVvJZiTUAQ)
:arrow_left: [Загальна інформація по підключенню (API)](https://hackmd.io/g3cItPVFStez0ql3Xj-2TA)

<details>
<summary>Служба підтримки XPAY</summary>
</br>

Телефон: [phone]
Email: [e-mail]
Telegram: @xpaysupportbot
</details>