---
id: identify
title: "Identify"
sidebar_label: "Identify"
hide_title: true
description: "Identify buyer"
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Ingress from "../../src/components/ingress/ingress.react";

<Ingress title="Identify buyer">
  Prior to invoking the AddInvoice function to initiate a purchase, the buyer
  must be authenticated using the endpoints detailed in this document.
</Ingress>

<Tabs defaultValue="phone" values={[
{ label: 'Phone Number', value: 'phone', },
{ label: 'Registration Number', value: 'registration', }
]}>

    <TabItem value="phone">
        The identification process for `Phone Number` involves the following steps. Only valid if no registration number exists:

        1. Dispatch an OTP challenge to the buyer via SMS using the `Identify buyer` endpoint.
        2. Validate the OTP with the `Verify` endpoint using the OTP from the challenge. This returns a list of organizations for which the buyer has purchasing rights.
        3. Utilize the token returned in step 1 when invoking AddInvoice. Refer to [AdditionalInformation](/docs/paymentsApi/integration/creating-purchases/addinvoice#additionalinformation) in Add Invoice.

   </TabItem>

    <TabItem value="registration">
        The identification process for `Registration Number` involves the following steps:

        1. Request an OTP challenge using the `Identify buyer` endpoint.
        2. Validate the OTP with the `Verify` endpoint. This returns a list of organizations for which the buyer has purchasing rights.
        3. Utilize the token returned in step 1 when invoking AddInvoice. Refer to [AdditionalInformation](/docs/paymentsApi/integration/creating-purchases/addinvoice#additionalinformation) in Add Invoice.

   </TabItem>
</Tabs>
<div>
  <a href="/img/b2b/b2b_identification.png" target="_blank">
    <img src="/img/b2b/b2b_identification.png" alt="" />
  </a>
</div>

### Initiate buyer identification

This endpoint is used to initiate a new identification. Depending on the means of identification, either SMS or registration number, the identification flow is slightly different.
A token is returned, which is subsequently used to validate any OTP and the AddInvoice request.

#### Registration number (CivRegNo)

When identifying the end customer using registration number the request is immediately validated. The returned token can be used to fetch organizations and to make purchases as soon as it is returned.

<Tabs defaultValue="req" values={[
{ label: 'Request', value: 'req', },
{ label: 'Response', value: 'res', }
]}>

<TabItem value="req">

```json
POST /b2b/{{countryCode}}/identify HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
    "Type": "RegistrationNumber",
    "Value": "198010011016"
}
```

</TabItem>

<TabItem value="res">

```json
Status: 202 Accepted
/* Body */
{
    "data": {
        "token": "YeJA5TTGBFtC-xNwKiBOAQ"
    }
}
```

</TabItem>
</Tabs>

#### Phone

The request below will cause a text message with an password to be sent to the supplied phone number.

<Tabs defaultValue="req" values={[
{ label: 'Request', value: 'req', },
{ label: 'Response', value: 'res', }
]}>

<TabItem value="req">

```json
POST /b2b/{{countryCode}}/identify HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
    "Type": "Phone",
    "Value": "+46731234567"
}
```

</TabItem>

<TabItem value="res">

```json
Status: 202 Accepted
/* Body */
{
    "data": {
        "token": "YeJA5TTGBFtC-xNwKiBOAQ"
    }
}
```

</TabItem>
</Tabs>

### Verify OTP

This endpoint is used to verify the OTP with the password entered by the buyer. After the OTP has been successfully verified, the organizations for which the buyer has purchasing rights are displayed.
It's important to store the returned token, as it is required to authorize the AddInvoice request.

Note that if identification has been done with registration number, no password has to be supplied.

#### Registration number (CivRegNo)

<Tabs defaultValue="req" values={[
{ label: 'Request', value: 'req', },
{ label: 'Response', value: 'res', }
]}>

<TabItem value="req">

```json
POST /b2b/{{countryCode}}/identify/{{token}}/verify HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{}
```

</TabItem>

<TabItem value="res">

```json
Status: 200 OK
{
    "data": {
        "organizations": [
            {
                "id": "5567164818",
                "name": "Swedec AB"
            }
        ]
    }
}
```

</TabItem>
</Tabs>

#### Phone

<Tabs defaultValue="req" values={[
{ label: 'Request', value: 'req', },
{ label: 'Response', value: 'res', }
]}>

<TabItem value="req">

```json
POST /b2b/{{countryCode}}/identify/{{token}}/verify HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
    "Otp": "519943"
}
```

</TabItem>

<TabItem value="res">

```json
Status: 200 OK
{
    "data": {
        "organizations": [
            {
                "id": "5567164818",
                "name": "Swedec AB"
            }
        ]
    }
}
```

</TabItem>
</Tabs>

| Http status code | Description                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 200              | Identity verified                                                                                                                |
| 202              | OTP challenge sent through SMS                                                                                                   |
| 400              | Error, refer to returned problem details                                                                                         |
| 401              | Unauthorized, token verification needed. See: [Authentication](/docs/manage/getting-started/authentication) for more information |
| 403              | Permissions needed                                                                                                               |

## Data Model

### Request

##### Request headers

| Header            | Required | Explanation                                                                                                             |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | Yes      | Instructions on how to generate the Bearer token value can be found [here](/docs/manage/getting-started/authentication) |

##### Request path parameters

| Parameter       | Required | Explanation                                                                       |
| --------------- | -------- | --------------------------------------------------------------------------------- |
| **countryCode** | Yes      | The country where the purchase is made. (SE, NO or FI)                            |
| **token**       | Yes      | A unique token for the identification. Used to verify a OTP.                      |

##### Request body

###### Initiate buyer identification

| Property  | Required | Explanation                               | Type   | Notes                                                                           |
| --------- | -------- | ----------------------------------------- | ------ | ------------------------------------------------------------------------------- |
| **type**  | Yes      | The type of OTP method                    | enum   | 1 = Phone, where OTP challenge is delivered by SMS <br/>2 = RegistrationNumber  |
| **Value** | Yes      | Phone number or Registration Number       | string | Include countryCode                                                             |

###### Verify OTP

| Property | Required | Explanation                                 | Type   | Notes                                                              |
| -------- | -------- | ------------------------------------------- | ------ | ------------------------------------------------------------------ |
| **Otp**  | Yes      | The challenge password entered by the buyer | number | Received by SMS from Walley. Only required if identifying by phone |