OKB

The integration with OKB is used to identify an individual by their personal data.

The service can run several verification strategies for a single subject in a single request and return an aggregated result.

Strategies:

person_identify_v2 — identification by the subject's personal data, verifying the match of the phone number, full name, and card.

The list of supported strategies may be expanded.

You must pass these request headers in every request:

Name	Type	Required	Description
`X-Api-Key`	string	Yes	Unique shop identifier
`X-Signature`	string	Yes	Request signature

The signature is generated using secret_key — the secret key found in the merchant's shop settings.

Identification by transaction

Method: POST

Production: https://api.pay.kvell.group/v1/person/scoring/okb/transaction
Stage: https://api.pay.stage.kvell.group/v1/person/scoring/okb/transaction

Request body parameters

Name	Data type	Required	Description
`okb_api_key`	string	Yes	Personal access token issued after registering with OKB
`strategy_code`	string	Yes	Strategy to run
`person`	json	Yes	Individual object
∟`first_name`	string	Yes	Individual's first name in uppercase. Allowed characters: Russian letters, hyphen, space, period
∟`last_name`	string	Yes	Individual's last name in uppercase. Allowed characters: Russian letters, hyphen, space, period
∟`second_name`	string	Yes	Individual's patronymic in uppercase. Allowed characters: Russian letters, hyphen, space, period
∟`phone`	string	Yes	Individual's mobile phone number in the format `7dddddddddd`
∟`birth_date`	string	Yes	Individual's date of birth in the format `YYYY-MM-DD`
`consent`	json	Yes	Object containing the set of parameters about consent to the service request
∟`received_at`	string	Yes	Date the consent to perform the request was obtained, in the format `YYYY-MM-DD`
∟`responsibility_flag`	bool	Yes	Flag indicating awareness of liability for violating consent collection rules: `true` — the client is aware, `false` — not aware
∟`was_received`	bool	Yes	Flag indicating whether consent for the service request was obtained: `true` — consent was given, `false` — consent was not given
`extra_data`	json	Yes	Additional strategy parameters
∟`transaction`	string	Yes	Number of a successful transaction on the merchant's side
∟`client_id`	bool	int	Client (financial institution) identifier issued by OKB

Request example

{
  "okb_api_key": "okb_api_key",
  "strategy_code": "person_identify_v2",
  "person": {
    "first_name": "АРТЁМ",
    "last_name": "АРТЁМОВ",
    "second_name": "АРТЁМОВИЧ",
    "phone": "79996660101",
    "birth_date": "1975-02-01"
  },
  "consent": {
    "received_at": "2025-09-22",
    "responsibility_flag": true,
    "was_received": true
  },
  "extra_data": {
    "transaction": "99ad8b11-48b8-41ea-85b7-29136d714fb1",
    "client_id": 9000
  }
}

Building the signature

The X-Signature signature is generated by concatenating X-Api-Key, json <request body>, and secret_key. sha256 is computed from the resulting string:

sha256({x-api-key}{json <request body>}{secret_key})

Response

{
  "status": true,
  "data": {
    "person_identify_v2": {
      "params": {
        "result": {
          "hit": "1.0",
          "result": "1.0"
        }
      },
      "is_hit": true
    }
  },
  "message": "OK",
  "request_id": "72e1b179-7e1e-441c-bb85-9a7343e8fb19"
}

Name	Type	Description
`data`	json	Payload: resulting information about the strategy calculations
∟`person_identify_v2`	json	Strategy
∟`is_hit`	string	Flag indicating whether the subject was found: `true` — hit (subject found), `false` — no hit (subject not found)
∟`params`	string	Model calculation result parameters
∟`result`	json	Object
∟`hit`	string	Hit
∟`result`	string	Model verification result
`message`	string	Short status message for the request
`request_id`	string	Unique request identifier
`status`	bool	Response status

Possible response combinations:

result = 1 + hit = 1 — the card matches the phone number;
result = 0 + hit = 1 — the number was found, the card does not match;
result = 0 + hit = 0 — the number was not found.

Identification by card number