Skip to main content
API docs by Redocly

Everypay IAPI (0.8)

Download OpenAPI specification:Download

Спецификация OpenAPI 3.0 для интеграции с Everypay.

Введение

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

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

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

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

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

Авторизация

Ниже представлена схема для авторизации в сервисе 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 - 1 минута

Перенаправление пользователя для авторизации

После получения первичного кода необходимо направить пользователя на адрес /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"
}

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

Authorization

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

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

httpBasicAuth

В качестве логина используется client_id, в качестве пароля - client_secret

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Песочница

Доступ

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

Список доменов для песочницы

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

Третьи стороны (банки)

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

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

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

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

Authorizations:
None

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": {
    }
}

Балансы

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

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

Конечная точка используется для получения информации о балансе банковского счета с идентификатором 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": { },
  • "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
= 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": { },
  • "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
= 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": { },
  • "Links": {},
  • "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": {
    }
}

Статистика

Статистика

Получение статистики по запросам

Получение статистики по запросам

При указании параметра start_date_time необходимо указать параметр end_date_time. При этом дата начала должна быть больше, чем дата окончания и разница между датами не должна превышать один месяц (2 678 399 секунд)

Если период не указан, по умолчанию рассматривается текущий месяц

ВНИМАНИЕ: для использования метода API необходимо указать один из новых базовых API URL:

Authorizations:
httpBasicAuth
query Parameters
start_date_time
string <date-time> (ISODateTime)
Example: start_date_time=2024-12-01T00:00:00Z

Формат даты и времени

end_date_time
string <date-time> (ISODateTime)
Example: end_date_time=2024-12-31T23:59:59Z

Формат даты и времени

Responses

Response samples

Content type
application/json
{
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "endDateTime": "2019-08-24T14:15:22Z",
  • "granularity": "day",
  • "totalRequests": 500000,
  • "breakdown": {
    },
  • "granulated": [
    ]
}