Skip to main content

Введение

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

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

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

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

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

Коллекции Postman

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

Начало работы

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

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

Авторизация

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

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

flow Авторизации в Everypay IAPI

После прохождения авторизации партнёру выдаётся 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 внешних сервисов, не являются настоящими.

Типы авторизаций

ThirdPartyAuth

Используйте client_id / client_secret для авторизации

Security Scheme Type: OAuth2
Flow type: clientCredentials
Token URL: /oauth/token
Scopes:
  • iapi/third-parties -

    Получение списка сторон (ППУ и СПИУ)

Authorization

Security Scheme Type: OAuth2
Flow type: authorizationCode
Authorization URL: /oauth/authorize
Token URL: /oauth/token
Scopes:
  • iapi/accounts -

    Доступ к информации о счете

Внешние сервисы

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

Получение списка сторон (ППУ и СПИУ)

Authorizations:
ThirdPartyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Счета

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

Получение списка счетов

Предоставляется полный список счетов (с идентификаторами accountId), которые были авторизованы пользователем на стороне ППУ.

Authorizations:
Authorization
query Parameters
page
integer
Default: 0

Номер страницы

header Parameters
x-fapi-auth-date
string

Время последнего входа Пользователя в систему с TPP. Значение предоставляется в виде HTTP-date, как в разделе 7.1.1.1 [RFC7231]. Например, x-fapi-auth-date: Mon, 26 Aug 2019 12:23:11 GMT

x-fapi-customer-ip-address
string

IP-адрес Пользователя, если Пользователь в данный момент подключен к Стороннему Поставщику (залогинен в приложении Стороннего Поставщика).

x-fapi-interaction-id
string

RFC4122 UID, используемый в качестве идентификатора корреляции. Если необходимо, то ППУ передает обратно значение идентификатора корреляции в заголовке ответа x-fapi-interaction-id.

x-customer-user-agent
string

В заголовке указывается тип устройства (user-agent), который использует Пользователь. Сторонний Поставщик может заполнить это поле значением типа устройства (user-agent), указанным Пользователем. Если Пользователь использует мобильное приложение Стороннего Поставщика, Сторонний Поставщик проверяет, что строка типа устройства (user-agent) отличается от строки типа устройства (user-agent) на основе браузера.

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { },
  • "Links": {},
  • "Meta": {
    }
}

Получение детальной информации о счете

СПИУ получает детальную информацию о счете по идентификатору accountId (который был получен при вызове конечной точке списка счетов GET /accounts).

Authorizations:
Authorization
path Parameters
accountId
required
string

Идентификатор счета

header Parameters
x-fapi-auth-date
string

Время последнего входа Пользователя в систему с TPP. Значение предоставляется в виде HTTP-date, как в разделе 7.1.1.1 [RFC7231]. Например, x-fapi-auth-date: Mon, 26 Aug 2019 12:23:11 GMT

x-fapi-customer-ip-address
string

IP-адрес Пользователя, если Пользователь в данный момент подключен к Стороннему Поставщику (залогинен в приложении Стороннего Поставщика).

x-fapi-interaction-id
string

RFC4122 UID, используемый в качестве идентификатора корреляции. Если необходимо, то ППУ передает обратно значение идентификатора корреляции в заголовке ответа x-fapi-interaction-id.

x-customer-user-agent
string

В заголовке указывается тип устройства (user-agent), который использует Пользователь. Сторонний Поставщик может заполнить это поле значением типа устройства (user-agent), указанным Пользователем. Если Пользователь использует мобильное приложение Стороннего Поставщика, Сторонний Поставщик проверяет, что строка типа устройства (user-agent) отличается от строки типа устройства (user-agent) на основе браузера.

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { },
  • "Links": {},
  • "Meta": {
    }
}

Выписки

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

Получения идентификатора выписки statementId по идентификатору счета accountId

ППУ предоставляет конечную точку СПИУ для получения идентификатора выписки statementId по идентификатору счета accountId, который предоставляется при вызове конечной точки GET /accounts

Authorizations:
Authorization
path Parameters
accountId
required
string

Идентификатор счета

header Parameters
x-customer-user-agent
string

В заголовке указывается тип устройства (user-agent), который использует Пользователь. Сторонний Поставщик может заполнить это поле значением типа устройства (user-agent), указанным Пользователем. Если Пользователь использует мобильное приложение Стороннего Поставщика, Сторонний Поставщик проверяет, что строка типа устройства (user-agent) отличается от строки типа устройства (user-agent) на основе браузера.

x-fapi-auth-date
string

Время последнего входа Пользователя в систему с TPP. Значение предоставляется в виде HTTP-date, как в разделе 7.1.1.1 [RFC7231]. Например, x-fapi-auth-date: Mon, 26 Aug 2019 12:23:11 GMT

x-fapi-interaction-id
string

RFC4122 UID, используемый в качестве идентификатора корреляции. Если необходимо, то ППУ передает обратно значение идентификатора корреляции в заголовке ответа x-fapi-interaction-id.

x-fapi-customer-ip-address
string

IP-адрес Пользователя, если Пользователь в данный момент подключен к Стороннему Поставщику (залогинен в приложении Стороннего Поставщика).

x-idempotency-key
required
string <= 40 characters ^(?!\s)(.*)(\S)$

Не стандартный HTTP заголовок. Уникальный идентификатор запроса для поддержки идемпотентности. Обязательно для запросов POST к конечным точкам идемпотентного ресурса. Для других запросов не указывается.

Request Body schema: application/json
required
= 2 properties
required
object (DataStatementInitRequestComplexType)

Контейнер для данных

required
object (RiskType)

Раздел 'Risk' содержит индикаторы риска для конкретного запроса API, предоставленного Сторонним Поставщиком.

Responses

Request samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { }
}

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { },
  • "Meta": {
    }
}

Массовое получение идентификаторов выписок statementId по идентификатору счета accountId

ППУ предоставляет конечную точку СПИУ для массового получения идентификаторов выписок statementId по идентификатору счета accountId, который предоставляется при вызове конечной точки GET /accounts

Authorizations:
Authorization
path Parameters
accountId
required
string

Идентификатор счета

header Parameters
x-customer-user-agent
string

В заголовке указывается тип устройства (user-agent), который использует Пользователь. Сторонний Поставщик может заполнить это поле значением типа устройства (user-agent), указанным Пользователем. Если Пользователь использует мобильное приложение Стороннего Поставщика, Сторонний Поставщик проверяет, что строка типа устройства (user-agent) отличается от строки типа устройства (user-agent) на основе браузера.

x-fapi-auth-date
string

Время последнего входа Пользователя в систему с TPP. Значение предоставляется в виде HTTP-date, как в разделе 7.1.1.1 [RFC7231]. Например, x-fapi-auth-date: Mon, 26 Aug 2019 12:23:11 GMT

x-fapi-interaction-id
string

RFC4122 UID, используемый в качестве идентификатора корреляции. Если необходимо, то ППУ передает обратно значение идентификатора корреляции в заголовке ответа x-fapi-interaction-id.

x-fapi-customer-ip-address
string

IP-адрес Пользователя, если Пользователь в данный момент подключен к Стороннему Поставщику (залогинен в приложении Стороннего Поставщика).

x-idempotency-key
required
string <= 40 characters ^(?!\s)(.*)(\S)$

Не стандартный HTTP заголовок. Уникальный идентификатор запроса для поддержки идемпотентности. Обязательно для запросов POST к конечным точкам идемпотентного ресурса. Для других запросов не указывается.

Request Body schema: application/json
required
= 2 properties
required
object (DataStatementInitRequestComplexType)

Контейнер для данных

required
object (RiskType)

Раздел 'Risk' содержит индикаторы риска для конкретного запроса API, предоставленного Сторонним Поставщиком.

Responses

Request samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { }
}

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { },
  • "Meta": {
    }
}

Получения выписки по идентификатору счета и идентификатору выписки

ППУ предоставляет конечную точку СПИУ для получения выписки по идентификатору счета и идентификатору выписки.

Authorizations:
Authorization
path Parameters
accountId
required
string

Идентификатор счета

statementId
required
string

Идентификатор выписки

query Parameters
page
integer
Default: 0

Номер страницы

fromBookingDateTime
string <date-time> (ISODateTime)

Дата и время начала фильтрации списка транзакций.

toBookingDateTime
string <date-time> (ISODateTime)

Дата и время окончания фильтрации списка транзакций.

header Parameters
x-fapi-auth-date
string

Время последнего входа Пользователя в систему с TPP. Значение предоставляется в виде HTTP-date, как в разделе 7.1.1.1 [RFC7231]. Например, x-fapi-auth-date: Mon, 26 Aug 2019 12:23:11 GMT

x-fapi-customer-ip-address
string

IP-адрес Пользователя, если Пользователь в данный момент подключен к Стороннему Поставщику (залогинен в приложении Стороннего Поставщика).

x-fapi-interaction-id
string

RFC4122 UID, используемый в качестве идентификатора корреляции. Если необходимо, то ППУ передает обратно значение идентификатора корреляции в заголовке ответа x-fapi-interaction-id.

x-customer-user-agent
string

В заголовке указывается тип устройства (user-agent), который использует Пользователь. Сторонний Поставщик может заполнить это поле значением типа устройства (user-agent), указанным Пользователем. Если Пользователь использует мобильное приложение Стороннего Поставщика, Сторонний Поставщик проверяет, что строка типа устройства (user-agent) отличается от строки типа устройства (user-agent) на основе браузера.

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { },
  • "Links": {},
  • "Meta": {
    }
}

Балансы

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

Баланс банковского счета

Конечная точка используется для получения информации о балансе банковского счета с идентификатором accountId.

Authorizations:
Authorization
path Parameters
accountId
required
string

Идентификатор счета

header Parameters
x-fapi-auth-date
string

Время последнего входа Пользователя в систему с TPP. Значение предоставляется в виде HTTP-date, как в разделе 7.1.1.1 [RFC7231]. Например, x-fapi-auth-date: Mon, 26 Aug 2019 12:23:11 GMT

x-fapi-customer-ip-address
string

IP-адрес Пользователя, если Пользователь в данный момент подключен к Стороннему Поставщику (залогинен в приложении Стороннего Поставщика).

x-fapi-interaction-id
string

RFC4122 UID, используемый в качестве идентификатора корреляции. Если необходимо, то ППУ передает обратно значение идентификатора корреляции в заголовке ответа x-fapi-interaction-id.

x-customer-user-agent
string

В заголовке указывается тип устройства (user-agent), который использует Пользователь. Сторонний Поставщик может заполнить это поле значением типа устройства (user-agent), указанным Пользователем. Если Пользователь использует мобильное приложение Стороннего Поставщика, Сторонний Поставщик проверяет, что строка типа устройства (user-agent) отличается от строки типа устройства (user-agent) на основе браузера.

Responses

Response samples

Content type
application/json
{
  • "Data": {
    },
  • "Risk": { },
  • "Meta": {
    }
}