---
# System prepended metadata

title: '[40015] Get Widget Link to Pass BankID/Diia Identification'

---

[УКР](https://hackmd.io/Avzys4G1QreAKnIjaKyn1Q) | ENG
![](https://i.imgur.com/Jnu9hNn.jpg)
:arrow_left: [Guide](https://hackmd.io/pa6TRNZTTa67jO_qYDuRBQ)

# [40015] Get Widget Link to Pass BankID/Diia Identification

## Usage

Request [40015] is used to get the link of the widget for passing the ["BankID"](https://en.wikipedia.org/wiki/BankID) or ["Diia"](https://en.wikipedia.org/wiki/Diia) identification.


![](https://i.imgur.com/OheSPu4.png)



## Request

*See the description of the "Partner", "KeyAES" and "Sign" attributes in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)".*


### Data Structure

Data structure for this operation is formed from the following parameters:


:::info
<details>
<summary>Data structure formation (examples are below)</summary>
<br>

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


|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
|`UserID`|No |String|Unique client identifier in the Partner system.|`Uwuh0B5GQVuokYSL`|
| `Phone` | Yes | String | Client phone number in the format "380xxxxxxxxxxxx". |`380679335544`|
| `Email` | No | String | Client email. |`index@gmail.com`|
| `FirstName` | No | String | Client name. |`Oleg`|
| `MiddleName` | No | String | Client middle name. |`Mykhaylovich`|
| `LastName` | No | String | Client last name. |`Podilskyi`|
| `RedirectURL` | No | String | URL, to which the client will be redirected after passing the identification procedure.| `https://partner.com/resul_page`|
| `CallbackURL` | Yes | String | URL, where the callback will be sent with the identification status after passing the identification procedure.| `https://partner.com/callback/xpass`|
|`Transaction`|Yes|Structure|Structure transmits transaction data. See section "[Transaction Structure](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#2-Data)".|See example below.|


:::success
<details>
<summary>Example of the request [40015]</summary>
<br>

~~~md
{
   "Partner": {
     "PartnerToken": "c6b218dc-e95c-4190-8850-960246eaab18",
     "OperationType": 40015
   },
   "Data": "{\"Email\": \"mail@ukr.net\", \"Phone\": \"380979011321\", \"LastName\": \"Podilskyi\", \"FirstName\ ": \"Oleg\", \"MiddleName\": \"Mykhaylovich\", \"CallbackURL\": \"https://partner.com/callback/xpass\", \"Transaction\": {\"TransactionID\": \"identity.e9e6e67e-7ddb-11ec-a42c-926b407ba61b\"}}",
  "KeyAES": "",
  "Sign": ""
}
~~~
</details>
:::


## Response

*See the general information on the response structure formation in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ?view#Response-Structure)"*.

### Data Structure

Successful response to the request [40015] contains a link in the form of a string with the name `URI` in the "Data" structure:

|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `URI` |Yes| String | Link to the "BankID/Diia" widget. |`https://stage-mapi.xpay.com.ua/uk/frame/widget/bank-id/691fafc9-5d64-46b5-22ba-85ce61cc26be`|
| `uuid` | Yes | String | Unique identifier linking widget requests. | `f3cd72b6-e1ea-406f-9b44-a9b93b401b7f` |


### Response Examples

:::success
<details>
<summary>Operation Successfully Completed</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>Operation Failed - "User not found"</summary>
<br>

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


## GET Request

Next, you need to open the page received in the response structure to the client: "URI".
After the identification procedure is completed, a GET request will be sent to the address from the "CallbackURL" parameter with the following parameters:


|Parameter|Required|Type|Description|Example|
|:----:|:----:|:----:|----|:----:|
| `command` | Yes | String | Request type: </br> - "success" - when success; </br> - "error" - when error.|`success` or `error` |
| `operation_id` | Yes | String | Unique operation identifier in the Operator system. | `37500` |
| `txn_id` | Yes | String | Unique transaction identifier in the Operator system. | `321455` |
| `partner_txn_id` | Yes | String | Unique transaction identifier in the Partner system, sent in request [40015]. | `453135c6e2` |
| `uuid` | Yes | String | Unique identifier linking widget requests. | `f3cd72b6-e1ea-406f-9b44-a9b93b401b7f` |
| `account` | Yes | String | Unique client identifier in the Partner system: phone or email. | `380638754213` |
| `txn_date` |Yes|String| Date and time of operation in format: YYYYMMDD_HHMMSS.| `20190301_180233` |
| `sign` |No|String| Signature is formed using a private key from data strings [concatenation](https://en.wikipedia.org/wiki/Concatenation): </br> `command`+`operation_id`+ `txn_date`+`account`+ `txn_id`+`partner_txn_id`. </br> See the signature generation algorithm in the section "[General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)". |`uDzPcuDjEFlC2FG-2Mjr566GKGIArfK-kcIA3LYTcXmavB3-9QBGmlVyU2yXG64-TM4qDq2kMBxXOQR-ueBMDcYgYkycyTd-Y8Q%3D%3D`|


:::success
<details>
<summary>Example of string formation for "sign" signature </summary>
<br>
Request data:

~~~md
command=success
operation_id=37500
txn_date=20190301_180233
account=380638754213
txn_id=321456
partner_txn_id=453135c6e2
~~~
Signature string:
~~~md
success3750020190301_180233380638754213321456453135c6e2
~~~
</details>
:::


## Reference Materials

General parameters of the XPAY system are given in the section ["Reference Materials"](https://hackmd.io/16yLv895Qo-FWTvrWWQwbg):  operation types, payment types, response codes, operation status, reasons of operation rejection, etc.


![](https://i.imgur.com/17gAyWb.png)
:arrow_left: [Guide](https://hackmd.io/pa6TRNZTTa67jO_qYDuRBQ)
:arrow_left: [General API Integration Information](https://hackmd.io/ijxPm0xtTpycgTjuU_NHQQ)

<details>
<summary>XPAY Support</summary>
</br>

Phone: +38 093 891 92 00
Email: info@xpay.com.ua
Telegram: @xpaysupportbot
</details>













