Everypay IAPI (0.9)

Для начала работы необходимо зарегистрировать своё приложение. Для этого необходимо отправить заявку на hello@everypay.io с реквизитами компании.

В заявке необходимо предоставить:

• данные о компании - ИНН/КПП, название, контакты для связи и ответственное лицо,
• ссылка для перенаправления запросов авторизации OAuth (redirect_url).

Ссылок для перенаправления запросов может быть несколько: для разработки, для тестовой среды, для stage и т.п.

В ответ вы получите client_id и client_secret, с которыми и будете запрашивать данные.

Коллекции Postman

Для упрощения процесса интеграции можете использовать коллеции и настройку окружения Postman:

• Коллекция запросов с примерами
• Окружение для Postman

Процесс взаимодействия с API Everypay состоит из нескольких шагов:

1. Получение списка внешних сервисов (поставщики платежных услуг, сервисные поставщики информационных услуг )
2. Получение кода (third-party-code) для авторизации пользователя во внешних сервисах
3. Перенаправление пользователя на страницу авторизации во внешнем сервисе
4. Получение кода авторизации
5. Обмен кода авторизации на токены
6. Обращение к ресурсам API

Ниже представлена схема для авторизации в сервисе everypay с помощью внешней стороны (банка).

Процесс авторизации схож с OAuth 2.0 Authorization Code

После прохождения авторизации партнёру выдаётся access_token и refresh_token.

Для начала нужно сгенерировать первоначальный код. Далее он поможет определить пользователя в процессе авторизации. Необходимо выполнить POST запрос по адресу /oauth/third-party-code. Формат тела запроса - application/json. Необходимые параметры:

• type - должен быть указан external,
• user_id - должен быть указан идентификатор сервиса партнёра, от лица которого запрашивается доступ. Тип - string.

В запросе необходимо использовать Basic авторизацию. В качестве логина должен быть использован client_id, а в качестве пароля - client_secret.

Пример тела запроса:

{
    "type": "external",
    "user_id": "1"
}

Пример тела ответа:

{
    "code": "code"
}

Время жизни параметра code - 10 минут

После получения первичного кода необходимо направить пользователя на адрес /oauth/authorize. Основные параметры взяты из спецификации OAuth 2.0 Authorization Code:

• client_id,
• redirect_uri,
• response_type со значением third_party_code,
• scope. Должен быть в формате urlencoded,
• code_challenge. Должен быть в формате base64 urlencoded,
• code_challenge_method. Поддерживается plain и S256,
• state (рекомендуется).

Для успешной интеграции необходимо два дополнительных параметра:

• third_party - внешний сервис (банк) для которого партнёр хочет получить токены,
• code - первичный код авторизации.

Пример итоговой ссылки для начала авторизации:

https://id.everypay.io/oauth/authorize
    ?client_id=partner
    &redirect_uri=https://example.com
    &response_type=third_party_code
    &scope=iapi%2Fthird-parties%20iapi%2Faccounts
    &code_challenge=73oehA2tBul5grZPhXUGQwNAjxh69zNES8bu2bVD0EM
    &code_challenge_method=S256
    &state=example_state
    &third_party=example_bank
    &code=code

При возникновении ошибки во время авторизации (после перехода по ссылке) возможен один из двух вариантов:

• В случае валидного redirect_uri пользователь будет перенаправлен на него;
• В случае невалидного redirect_uri ошибка будет отображена на той же странице в формате JSON.

Обязательное поле error, которое содержит низкоуровневое текстовое описание ошибки. Поле error_description - подробное описание ошибки, не является обязательным.

После того, как пользователь пройдёт авторизацию во внешнем сервисе (банке) он будет перенаправлен на указанный redirect_uri с параметрами:

• code,
• state (если он был передан ранее).

Полученный code необходимо обменять на токены. Для этого необходимо выполнить POST запрос на адрес /oauth/token. Формат тела запроса - application/x-www-form-urlencoded. В теле запроса указываются параметры согласно спецификации OAuth 2.0 Authorization Code:

• grant_type со значением third_party_authorization_code,
• client_id,
• client_secret,
• code,
• redirect_uri,
• code_verifier.

Пример тела запроса:

{
    "grant_type": "third_party_authorization_code",
    "client_id": "partner",
    "client_secret": "example_secret",
    "code": "code",
    "redirect_uri": "https://example.com",
    "code_verifier": "code_verifier"
}

Пример ответа:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "access_token",
    "refresh_token": "refresh_token"
}

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

Для обмена refresh_token на новую пару токенов необходимо выполнить POST запрос на адрес /oauth/token. Формат тела запроса - application/x-www-form-urlencoded. В теле запроса указываются параметры согласно спецификации OAuth 2.0 Authorization Code:

• client_id,
• client_secret,
• grant_type со значением refresh_token,
• refresh_token.

Пример тела запроса:

{
    "client_id": "partner",
    "client_secret": "example_secret",
    "grant_type": "refresh_token",
    "refresh_token": "refresh_token"
}

Пример ответа:

{
    "token_type": "Bearer",
    "expires_in": "86400",
    "access_token": "access_token",
    "refresh_token": "refresh_token"
}

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

Для того, чтобы настроить работу с песочницей необходимо заменить базовый домен для запросов с *.everypay.io на *-beta.everypay.io, т.е. добавить -beta перед .everypay.io во всех используемых доменах.

• id-beta.everypay.io - для авторизации,
• iapi-beta.everypay.io - для API.

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

Работа с согласиями

Стороны информационного взаимодействия (ППУ и СПИУ)

Получение информации об учетных записях на стороне взаимодействия

Взаимодействие с выписками

Взаимодействие с балансами