Обзор HighHelp API

В этом разделе описаны общие принципы работы API HighHelp: структура URL, форматы запросов и ответов, а также связь API с основными сценариями интеграции.

Подробнее про модель сущностей и термины см. в разделе Основные понятия.

Назначение API HighHelp

API HighHelp используется для сервер-серверной (H2H) интеграции платежных сценариев и вспомогательных операций.

С помощью API можно:

  • создавать и обрабатывать P2P-платежи и выплаты;

  • выполнять e-commerce-платежи по картам (ECOM);

  • получать информацию о заявках и их статусах;

  • запрашивать баланс кассы;

  • получать служебные данные (списки банков, поддерживаемые методы оплаты и т.п.).

При работе через платежный виджет HighHelp часть операций выполняется на стороне виджета, но в основе виджета также используются те же API-методы.

Виды интеграции и разделы документации

Основные варианты интеграции:

Базовые принципы работы API

Протокол и формат данных

  • Все обращения к API выполняются по HTTPS.

  • Формат данных — JSON, кодировка UTF-8.

  • В запросах и ответах используется заголовок content-type: application/json.

Примеры URL API приведены в руководствах по интеграции, например:

Конкретные базовые URL для продакшн- и тестового окружения предоставляет ваш менеджер при подключении.

Версионирование и структура URL

Версия API указывается в пути, например:

  • /api/v1/payment/…​

  • /api/v1/bank/…​

Структура URL для платежных операций имеет вид:

  • /api/v1/payment/{product}/{flow}

  • /api/v1/payment/{product}/{flow}/info

  • /api/v1/payment/{product}/{flow}/confirm-3ds-result

где:

  • {product}-- продукт (p2p, ecom и др.);

  • {flow} — направление или операция (payin, payout и др.).

Для сервисных методов используются отдельные пути, описанные в Сервисных методах API.

HTTP-методы и ответы

  • Для всех текущих методов API используется HTTP-метод POST.

  • Успешный ответ содержит JSON-объект со статусом операции и идентификаторами заявки.

  • Технические ошибки могут возвращаться с кодами HTTP из диапазона 4xx или 5xx и телом с описанием ошибки.

Бизнес-состояние операции передается в полях ответа:

  • status — основной статус (processing, success, decline, error и др.);

  • sub_status — подстатус (например, new, requisites, awaiting_3ds_result, payout_process и др.);

  • status_description — текстовое описание статуса и причины отказа при необходимости.

Полный перечень статусов и подстатусов см. в разделе Коды статусов.

Аутентификация и подпись запросов

Все запросы к API HighHelp должны быть аутентифицированы и подписаны.

При обращении к API используются следующие заголовки:

  • x-access-merchant-id — идентификатор кассы (проект мерчанта).

  • x-access-signature — цифровая подпись запроса.

  • x-access-token — ключ, по которому платформа идентифицирует пару ключей.

  • x-access-timestamp — время формирования подписи (Unix time, UTC, в секундах).

Подпись формируется на основе тела запроса, нормализованного в детерминированную строку, закодированную в Base64Url, и значения timestamp.

Подробный алгоритм нормализации, правила формирования подписи и примеры кода см. в разделе Аутентификация и подпись.

Оповещения и асинхронные операции

Для части операций результат обработки передается асинхронно через оповещения:

  • при создании платежей и выплат API возвращает первичный статус (status, sub_status);

  • при дальнейшем изменении статуса платформа отправляет HTTP-запрос на URL, указанные в параметрах merchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url;

  • каждое оповещение содержит текущий статус заявки и доп. данные (сумма, валюта, реквизиты, данные для аутентификации и др.).

Оповещения также подписываются, и перед обработкой на стороне мерчанта рекомендуется:

  • проверить цифровую подпись;

  • реализовать идемпотентную обработку (игнорировать уже обработанные статусы);

  • логировать ключевые поля (идентификаторы, статусы, суммы).

Подробности см.:

Справочная информация

Дополнительные справочники, на которые опираются все методы API:

Что читать дальше

Рекомендуем следующий порядок знакомства с API:

  1. Быстрый старт — минимальный сценарий для выполнения тестового платежа.

  2. Аутентификация и подпись — подробная схема заголовков и примеры кода для подписи запросов.

  3. Обзор ECOM H2H и Общие требования для P2P H2H — выбор сценария интеграции.

  4. Сервисные методы API и Баланс кассы — вспомогательные операции.

  5. Примеры интеграции SDK — рабочие примеры запросов к API на популярных языках.