API Руководство по интеграции

В этом руководстве объясняется весь процесс интеграции API, от регистрации до получения токенов и выполнения аутентифицированных запросов API.

1. Процесс адаптации

Что такое онбординг?

Регистрация — это однократный процесс настройки для получения учетных данных API:

username
password
consumer_key
consumer_secret

Чтобы начать этот процесс, вам понадобится токен регистрации, предоставленный Paylov.

Рекомендации по безопасности

После завершения регистрации ваши username и password устанавливаются вами, а consumer_key и consumer_secret выдаются Paylov.

Сохраняйте все четыре учетных данных строго конфиденциальными. Относитесь к ним как к паролям — никогда не передавайте их, никогда не раскрывайте их в клиентском коде или общедоступных репозиториях и храните их в безопасном диспетчере секретов или в переменных среды.

Если ваш consumer_secret утек или стал доступен неавторизованной стороне, немедленно сообщите об этом в службу поддержки Paylov — учетные данные будут немедленно отозваны.

Шаг 1. Проверьте токен регистрации

Сначала убедитесь, что ваш токен регистрации действителен.

Конечная точка

http

GET {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Параметры

Требуется token — токен регистрации

Пример запроса

bash

curl -X GET "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"

Успешный ответ `200 OK`

json

{
  "status": "ok"
}

Ответ об ошибке `400 Bad Request`

json

{
  "error": "invalid_or_expired"
}

Шаг 2. Установите имя пользователя и пароль.

После проверки токена создайте свое имя пользователя и пароль. Взамен вы получите свои consumer_key и consumer_secret.

Требования к паролю

Ваш пароль должен:

быть длиной не менее 8 символов
содержать хотя бы одну строчную букву a-z
содержать хотя бы одну заглавную букву A-Z
содержать хотя бы одну цифру 0-9
содержать хотя бы один специальный символ, например !@#$%^&*

Примеры действительных паролей

Secure@Pass123!
MyP@s3W0rd
Tr0pic@lLh!eze

Примеры неверных паролей

password123 — без заглавных букв и специальных символов.
Pass123 — слишком коротко
PASSWORD123! — нет строчной буквы

Конечная точка

http

POST {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Заголовки запросов

http

Content-Type: application/json

Тело запроса

json

{
  "username": "...",
  "password": "..."
}

Пример запроса

bash

curl -X POST "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"   
-H "accept: */*"   
-H "Content-Type: application/json"   
-d '{
    "username": "...",
    "password": "..."
  }'

Успешный ответ `200 OK`

json

{
  "consumer_key": "app_a1b2c3d4e5f6g7h8i9j0k1",
  "consumer_secret": "Ks8Lp90q0Rr1Ss2Tt3Uu4Vv5Ww6Xx7Yy8Zz9Aa0Bb1Cc2Dd3Ee",
  "username": "my_username"
}

Важные примечания

consumer_key и consumer_secret — ваши учетные данные API. Храните их надежно.
consumer_secret отображается только один раз. Если вы потеряете его, вам необходимо создать новые учетные данные.
Регистрационный токен можно использовать только один раз.
Храните свое имя пользователя и пароль в безопасности.

Активация аккаунта

После получения consumer_key и consumer_secret аккаунт не становится активным сразу. Пока аккаунт не будет активирован администраторами Paylov, получить access_token и отправлять API-запросы с этими учетными данными невозможно.

После завершения онбординга свяжитесь с Paylov по вопросу активации аккаунта и продолжайте интеграцию после получения подтверждения.

2. Получение токена доступа

Что такое токен доступа?

Токен доступа необходим для аутентифицированных запросов API. Включайте его в каждый вызов API.

Процесс запроса токена

Конечная точка

http

POST {BASE_URL}/merchant/oauth2/token/

Аутентификация

Используйте базовую аутентификацию, закодировав consumer_key и consumer_secret в формате base64.

Заголовки запросов

bash

Authorization: Basic base64(consumer_key:consumer_secret) # YycX3bGtsMnJfWH...
Content-Type: application/json

Тело запроса

json

{
  "grant_type": "password",
  "username": "some-username",
  "password": "strong-password"
}

grant_type обязательный — password или refresh_token
username — обязателен при grant_type=password
password — обязателен при grant_type=password

Примечание

Тело запроса принимается только в формате JSON. Если в любое поле передать null, вернётся 400 validation_error.

Шаг 1. Подготовьте базовую авторизацию

Объедините свой потребительский ключ и потребительский секрет в следующем формате:

text

consumer_key:consumer_secret

Затем закодируйте это значение в base64.

Шаг 2. Отправьте запрос токена

Пример запроса

bash

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/" \
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>" \
-H "Content-Type: application/json" \
-d '{
  "grant_type": "password",
  "username": "my_username",
  "password": "secure_password_123"
}'

Успешный ответ `200 OK`

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000
}

Объяснение ответа

access_token — токен для запросов API, действителен 1 час.
refresh_token — токен, используемый для получения нового токена доступа, действителен в течение 30 дней.
expires_in — время жизни токена доступа в секундах
refresh_expires_in — время жизни токена обновления в секундах

Ответ об ошибке `401 Unauthorized`

json

{
  "result": null,
  "error": {
    "code": "invalid_grant",
    "message": "Invalid credentials"
  }
}

this account not activated

После получения учётных данных через токен регистрации аккаунт не становится активным сразу. Пока администраторы Paylov не активируют аккаунт, запрос токена возвращает следующую ошибку:

json

{
  "result": null,
  "error": {
    "code": "invalid_grant",
    "message": "this account not activated"
  }
}

В этом случае учётные данные верны — обратитесь к администрации Paylov для активации аккаунта.

3. Выполнение запросов API с токеном доступа

Использование токена доступа

Включите токен доступа в заголовок Authorization каждого запроса API.

Формат заголовка

http

Authorization: Bearer YOUR_ACCESS_TOKEN

Пример запроса

bash

curl -X GET "https://{BASE_URL}/merchant/status/" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

4. Обновление токена доступа

Когда срок действия вашего токена доступа истечет, используйте токен обновления, чтобы получить новый. Вам не нужно повторно отправлять имя пользователя и пароль.

Конечная точка

http

POST {BASE_URL}/merchant/oauth2/token/

Заголовки запросов

http

Authorization: Basic base64(consumer_key:consumer_secret)
Content-Type: application/json

Тело запроса

json

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

refresh_token — обязателен при grant_type=refresh_token

Пример запроса

bash

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/" \
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>" \
-H "Content-Type: application/json" \
-d '{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Успешный ответ `200 OK`

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000
}

INFO

После успешного обновления старый refresh_token отзывается. Для следующих запросов используйте только новый refresh_token.

5. Отзыв токенов

Вы можете отозвать токен, чтобы предотвратить его дальнейшее использование. Отозвать можно только access_token.

Конечная точка

http

POST {BASE_URL}/merchant/oauth2/revoke/

Заголовки запросов

http

Content-Type: application/json

Тело запроса

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Пример запроса

bash

curl -X POST "https://{BASE_URL}/merchant/oauth2/revoke/" \
-H "Content-Type: application/json" \
-d '{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Успешный ответ `200 OK`

json

{
  "status": "success"
}

Ответ об ошибке `400 Bad Request`

json

{
  "result": null,
  "error": {
    "code": "invalid_token",
    "message": "Token not found or already revoked"
  }
}

6. Обработка ошибок

Все ошибки возвращаются в следующем формате:

json

{
  "result": null,
  "error": {
    "code": "invalid_grant",
    "message": "Invalid credentials"
  }
}

`400 Bad Request`

`code`	`message`	Причина
`invalid_request`	`Basic Authorization header required`	Заголовок `Authorization` отсутствует или не начинается с `Basic`
`invalid_request`	`Invalid Authorization header format`	`base64(consumer_key:consumer_secret)` имеет неверный формат
`invalid_request`	`username and password required`	Для `grant_type=password` не передан `username` или `password`
`invalid_request`	`refresh_token required`	Для `grant_type=refresh_token` не передан `refresh_token`
`unsupported_grant_type`	`Grant type '...' is not supported`	`grant_type` не равен `password` или `refresh_token`
`validation_error`	—	Поля тела запроса неверны или передан `null`
`invalid_token`	`Token not found or already revoked`	Отзываемый токен не найден или уже отозван
`invalid_or_expired`	`Token is invalid or expired`	Токен регистрации недействителен или истёк

`401 Unauthorized`

Для grant_type=password:

`code`	`message`	Причина
`invalid_grant`	`Invalid consumer key`	`consumer_key` неверный или неактивен
`invalid_grant`	`Invalid consumer secret`	`consumer_secret` неверный
`invalid_grant`	`IP address not in whitelist`	IP-адрес запроса не входит в список разрешённых
`invalid_grant`	`Invalid credentials`	Неверный `username` или `password`
`invalid_grant`	`this account not activated`	Аккаунт ещё не активирован администраторами
`invalid_grant`	`User account is locked`	Аккаунт заблокирован из-за многократного ввода неверного пароля

Для grant_type=refresh_token:

`code`	`message`	Причина
`invalid_client`	`Invalid consumer key`	`consumer_key` неверный или неактивен
`invalid_grant`	`Refresh token expired`	Срок действия `refresh_token` истёк
`invalid_grant`	`Invalid refresh token`	`refresh_token` неверный
`invalid_grant`	`Not a refresh token`	Вместо `refresh_token` передан другой токен
`invalid_grant`	`Refresh token invalid or expired`	`refresh_token` отозван или истёк
`invalid_grant`	`User credential inactive`	Аккаунт неактивен

7. Краткий справочник

API конечные точки

Метод	Конечная точка	Цель
`GET`	`/merchant/onboarding/`	Проверить токен регистрации
`POST`	`/merchant/onboarding/`	Завершить регистрацию
`POST`	`/merchant/oauth2/token/`	Получить или обновить токен доступа
`POST`	`/merchant/oauth2/revoke/`	Отозвать токен

Коды ошибок

Ошибка	Описание
`invalid_request`	Запрос имеет неверный формат
`invalid_client`	Потребительский ключ недействителен (при обновлении токена)
`invalid_grant`	Учётные данные или `refresh_token` недействительны, либо аккаунт неактивен
`unsupported_grant_type`	Тип гранта не поддерживается
`invalid_token`	Отзываемый токен не найден или уже отозван
`validation_error`	Поля тела запроса неверны
`invalid_or_expired`	Токен недействителен или срок его действия истек
`token_required`	Параметр токена отсутствует

API Руководство по интеграции ​

1. Процесс адаптации ​

Что такое онбординг? ​

Шаг 1. Проверьте токен регистрации ​

Конечная точка ​

Параметры ​

Пример запроса ​

Успешный ответ 200 OK ​

Ответ об ошибке 400 Bad Request ​

Шаг 2. Установите имя пользователя и пароль. ​

Требования к паролю ​

Примеры действительных паролей ​

Примеры неверных паролей ​

Конечная точка ​

Заголовки запросов ​

Тело запроса ​

Пример запроса ​

Успешный ответ 200 OK ​

Важные примечания ​

2. Получение токена доступа ​

Что такое токен доступа? ​

Процесс запроса токена ​

Конечная точка ​

Аутентификация ​

Заголовки запросов ​

Тело запроса ​

Шаг 1. Подготовьте базовую авторизацию ​

Шаг 2. Отправьте запрос токена ​

Пример запроса ​

Успешный ответ 200 OK ​

Объяснение ответа ​

Ответ об ошибке 401 Unauthorized ​

3. Выполнение запросов API с токеном доступа ​

Использование токена доступа ​

Формат заголовка ​

Пример запроса ​

4. Обновление токена доступа ​

Конечная точка ​

Заголовки запросов ​

Тело запроса ​

Пример запроса ​

Успешный ответ 200 OK ​

5. Отзыв токенов ​

Конечная точка ​

Заголовки запросов ​

Тело запроса ​

Пример запроса ​

Успешный ответ 200 OK ​

Ответ об ошибке 400 Bad Request ​

6. Обработка ошибок ​

400 Bad Request ​

401 Unauthorized ​

7. Краткий справочник ​

API конечные точки ​

Коды ошибок ​

API Руководство по интеграции

1. Процесс адаптации

Что такое онбординг?

Шаг 1. Проверьте токен регистрации

Конечная точка

Параметры

Пример запроса

Успешный ответ `200 OK`

Ответ об ошибке `400 Bad Request`

Шаг 2. Установите имя пользователя и пароль.

Требования к паролю

Примеры действительных паролей

Примеры неверных паролей

Конечная точка

Заголовки запросов

Тело запроса

Пример запроса

Успешный ответ `200 OK`

Важные примечания

2. Получение токена доступа

Что такое токен доступа?

Процесс запроса токена

Конечная точка

Аутентификация

Заголовки запросов

Тело запроса

Шаг 1. Подготовьте базовую авторизацию

Шаг 2. Отправьте запрос токена

Пример запроса

Успешный ответ `200 OK`

Объяснение ответа

Ответ об ошибке `401 Unauthorized`

3. Выполнение запросов API с токеном доступа

Использование токена доступа

Формат заголовка

Пример запроса

4. Обновление токена доступа

Конечная точка

Заголовки запросов

Тело запроса

Пример запроса

Успешный ответ `200 OK`

5. Отзыв токенов

Конечная точка

Заголовки запросов

Тело запроса

Пример запроса

Успешный ответ `200 OK`

Ответ об ошибке `400 Bad Request`

6. Обработка ошибок

`400 Bad Request`

`401 Unauthorized`

7. Краткий справочник

API конечные точки

Коды ошибок