Банковские переводы в России

Название Код Описание

Тип интеграции

H2C

Платеж через платежный виджет HighHelp

Валюта

RUB

Российский рубль

Страна

RU

Российская Федерация

Депозиты

Доступные методы для оплаты:
- payin-p2p-card
- payin-p2p-sbp
- payin-1-click
- payin-p2p-international
- payin-qr-sbp
- payin-p2p-mobile
- payin-p2p-card-international

Выплаты

Выплаты недоступны

Оплата

Создание заявки

POST https://api.hh-processing.com/api/v1/widget/payin

Параметры тела запроса при создании заявки P2P.

  • general  — информация о заявке

    • project_id  — идентификатор кассы, выданный HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта. Можно использовать любые буквы, цифры и символы в кодировке UTF-8.
      (string) (<= 255 символа)

    • merchant_callback_url — динамический URL для получения оповещений с промежуточной информацией: изменение статусов заявки, реквизиты для оплаты и т.п. Оповещения по финальным статусам заявки отправляются на URL, указанные в merchant_success_callback_url и merchant_decline_callback_url.
      (string<https-url>) (<= 2048 символа)

    • merchant_success_callback_url — динамический URL для получения оповещения при успешном завершении операции.
      (string<https-url>) (<= 2048 символа)

    • merchant_decline_callback_url — динамический URL для получения оповещения, если операция не завершилась успешно.
      (string<https-url>) (<= 2048 символа)

    • redirect_url — ссылка для перенаправления пользователя с платежной страницы после завершения платежа.
      (string<https-url>) (<= 2048 символа)

  • payment  — информация о платеже

    • amount  — сумма, которую оплачивает пользователь. Сумма указывается в дробных единицах. Подробнее см. Коды валют.
      (integer) (1 <= X <= 10000000000000)

    • currency  — код валюты платежа в формате ISO 4217 alpha-3. Подробнее см. Коды валют.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime — время жизни заявки в секундах. Максимальное время жизни — 10 минут. Если значение не указано, используется значение по умолчанию 10 минут.
      (integer) (300 <= X <= 600)

    • description — описание платежа или комментарий. Значение отображается в личном кабинете мерчанта.
      (string) (<= 255 символа)

    • extra_param — дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно с администратором HighHelp.
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

    • widget_method — код платежного метода, который будет предвыбран на платежной странице. Список методов см. в разделе Методы виджета (H2C).
      (string) (<= 32 символа)

  • sender — информация о банке, карте или номере телефона, с которого выполняется оплата

    • bank_symbol — банк, с которого клиент будет оплачивать заявку. Список банков см. в разделах Банки для предвыбора и Банки для P2P. Если банк не нужно предвыбирать, поле можно не заполнять.
      (string) (<= 32 символа)

  • customer  — информация об отправителе

    • id  — уникальный идентификатор пользователя (отправителя) в системе мерчанта.
      (string) (<= 255 символа)

    • ip_address  — IP-адрес отправителя.
      (string<ip-address>) (<= 255 символа)

    • country  — код страны пользователя в формате ISO 3166-1 alpha-2. Список поддерживаемых стран см. в разделе Коды стран.
      (string) (regex: ^[A-Z]{2}$)

    • language — код языка в формате ISO 639-1, который будет предвыбран на платежной странице. Если язык не указан, используется язык по умолчанию для страны. Список поддерживаемых языков см. в разделе Коды языков.
      (string) (regex: ^[a-z]{2}$)

    • customer_type — тип пользователя: ftd для первичного трафика, trust для вторичного трафика.
      (string) (regex: ^(ftd|trust)$)

    • email — адрес электронной почты отправителя.
      (string<email>) (<= 255 символа)

Поля, помеченные , являются обязательными.

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

curl https://api.hh-processing.com/api/v1/widget/payin \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "RUB-MIR-123456",
    "merchant_callback_url": "https://your-callback-domain.com/internal",
    "merchant_success_callback_url": "https://your-callback-domain.com/success",
    "merchant_decline_callback_url": "https://your-callback-domain.com/decline",
    "redirect_url": "https://your-web-site-url.com/order/page"
  },
  "payment": {
    "amount": 1500000,
    "currency": "RUB",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example",
    "widget_method": "payin-p2p-card"
  },
  "sender": {
    "bank_symbol": "sberbank"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "country": "RU",
    "language": "ru",
    "customer_type": "ftd",
    "email": "[email protected]"
  }
}'

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

{
  "status": "processing",
  "sub_status": "requisites",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "RUB-MIR-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

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

  • status  — статус обработки платежа. Список статусов см. в разделе Статусы операций и коды ошибок.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки платежа. Используется только для части статусов. Полный список комбинаций статусов и подстатусов см. в разделе Статусы операций и коды ошибок.
    (string) (<= 32 символа)

  • status_description — дополнительная информация о статусе. Используется при ошибке оплаты.
    (string) (<= 1024 символа)

  • request_id  — идентификатор платежа, который генерируется в платежной системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы, выданный HighHelp в процессе интеграции.
    (string) (<= 32 символа)

  • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта.
    (string) (<= 255 символа)

  • integration — дополнительная метаинформация о платеже

    • form_url  — ссылка на платежную страницу. На странице отображаются реквизиты для оплаты, платежная инструкция и другая необходимая информация.
      (string<https-url>) (<= 255 символа)

    • redirect_url — ссылка для перенаправления пользователя с платежной страницы после завершения платежа.
      (string<https-url>) (<= 2048 символа)

Поля, помеченные , являются обязательными.

Информация о заявке

POST https://api.hh-processing.com/api/v1/widget/payin/info

Параметры тела запроса для получения статуса заявки P2P.

  • general  — информация о заявке

    • project_id  — идентификатор кассы, выданный HighHelp в процессе интеграции.
      (string) (<= 32 символа)

    • payment_id  — идентификатор платежа.
      (string) (<= 255 символа)

Поля, помеченные , являются обязательными.

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

curl https://api.hh-processing.com/api/v1/widget/payin/info \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 8b03432e-385b-4670-8d06-064591096795' \
  -H 'x-access-signature: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
  "general": {
    "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
    "payment_id": "RUB-MIR-123456"
  }
}'

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

{
  "status": "processing",
  "sub_status": "awaiting_confirm",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "RUB-MIR-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 12000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

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

  • status  — статус обработки платежа. Список статусов см. в разделе Статусы операций и коды ошибок.
    (string) (<= 32 символа)

  • sub_status — подстатус обработки платежа. Используется только для части статусов. Полный список комбинаций статусов и подстатусов см. в разделе Статусы операций и коды ошибок.
    (string) (<= 32 символа)

  • status_description — дополнительная информация о статусе. Используется при ошибке оплаты.
    (string) (<= 1024 символа)

  • request_id  — идентификатор платежа, который генерируется в платежной системе HighHelp.
    (string) (<= 32 символа)

  • project_id  — идентификатор кассы, выданный HighHelp в процессе интеграции.
    (string) (<= 32 символа)

  • payment_id  — идентификатор платежа, уникальный в рамках кассы мерчанта.
    (string) (<= 255 символа)

  • payment_info  — информация о платеже

    • amount  — сумма заявки. Сумма указывается в дробных единицах. Подробнее см. Коды валют.
      (integer) (1 <= X <= 10000000000000)

    • old_amount  — сумма заявки до апелляции. Значение может отличаться от amount, если заявка была создана на одну сумму, а пользователь перевел другую. В этом случае в поле amount передается фактическая сумма, полученная от пользователя, а в поле old_amount — сумма, на которую заявка была создана. Если сумма не менялась, значения полей совпадают.
      (integer) (1 <= X <= 10000000000000)

    • initial_amount  — сумма, указанная при создании заявки. Значение не изменяется.
      (integer) (1 <= X <= 10000000000000)

    • currency  — код валюты платежа в формате ISO 4217 alpha-3. Подробнее см. Коды валют.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime — время жизни заявки в секундах.
      (integer) (300 <= X <= 600)

    • expiration_date — время, до которого заявка действительна, в формате Unix Timestamp (UTC).
      (integer) (X <= 2^32)

    • method — платежный метод, выбранный при создании платежа. Подробнее см. Платежные методы.
      (string) (<= 32 символа)

    • widget_method — код платежного метода платежной страницы. Подробнее см. Методы виджета (H2C).
      (string) (<= 32 символа)

    • type — тип платежа. Подробнее см. Типы платежей.
      (string) (<= 32 символа)

  • integration — дополнительная метаинформация о платеже

    • form_url  — ссылка на платежную страницу. На странице отображаются реквизиты для оплаты, платежная инструкция и другая необходимая информация.
      (string<https-url>) (<= 255 символа)

    • redirect_url — ссылка для перенаправления пользователя с платежной страницы после завершения платежа.
      (string<https-url>) (<= 2048 символа)

Поля, помеченные , являются обязательными.

Статусы платежей

Полный перечень статусов и подстатусов см. в разделе Статусы операций и коды ошибок.

Статус Подстатус Описание Действия мерчанта

error

Запрос отклонен из-за ошибки, связанной с параметрами платежа.

Обратитесь в поддержку

processing

new

Платеж создан и ожидает действий клиента.

Действия не требуются

requisites

Требуется ввод реквизитов, доступна ссылка на форму в integration.form_url.

Направьте клиента на форму оплаты

awaiting_confirm

Ожидается подтверждение оплаты клиентом. Возможна оплата через перенаправление или QR.

Дождитесь завершения оплаты

paid

Средства зафиксированы и ожидается финальное подтверждение.

Дождитесь завершения оплаты

dispute

no_payment

Клиент не выполнил оплату в течение времени жизни платежа (lifetime).

Действия не требуются

different_amount

Получена сумма, не совпадающая с заявленной.

Обратитесь в поддержку

confirm_timeout

Время ожидания подтверждения истекло, оплата не завершена.

Обратитесь в поддержку

decline

Платеж отклонен.

Сообщите клиенту об отказе

success

Платеж успешно подтвержден.

Действия не требуются

Оповещения

Рекомендуется реализовать проверку входящих оповещений на дубликаты. Ключ идемпотентности можно формировать по шаблону {project_id}:{payment_id}:{status}:{sub_status}. Повторные оповещения с тем же ключом следует игнорировать, чтобы исключить повторную обработку одной и той же заявки.

Каждое оповещение подписывается цифровой подписью HighHelp. Текущий публичный ключ для проверки подписи можно получить в панели администратора. Ключ уникален для каждой кассы. Алгоритм проверки подписи идентичен алгоритму формирования подписи при вызове API. Примеры проверки подписи приведены в разделе Аутентификация и подпись.

Предусмотрены три типа оповещений:

  • Информативные — оповещения по промежуточным статусам заявок. Оповещение отправляется при изменении статуса. URL задается в параметре merchant_callback_url при создании заявки.

  • Успешные — оповещения по заявкам, завершившимся в статусе success. URL задается в параметре merchant_success_callback_url.

  • Неуспешные — оповещения по заявкам, завершившимся в статусе decline или с ошибкой. URL задается в параметре merchant_decline_callback_url.

Информативные оповещения

Пример оповещения со статусом processing:awaiting_confirm:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "RUB-MIR-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-1-click",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan_hidden": "2202****6980",
    "card_holder_hidden": "Ко****ов",
    "bank_name": "alfa-bank",
    "bank_country": "RU",
    "currency": "RUB"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Замаскированные реквизиты в блоке recipient_requisites передаются только для статусов processing:awaiting_confirm и processing:paid. Для остальных статусов заявки реквизиты не передаются (например, "recipient_requisites": null).

Успешные оповещения

Оповещение отправляется, если заявка завершилась в статусе success.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "RUB-MIR-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 5000,
    "initial_amount": 3000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-1-click",
    "type": "payin"
  }
}

Неуспешные оповещения

Оповещение отправляется, если заявка завершилась в статусе decline.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "RUB-MIR-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": null,
    "widget_method": null,
    "type": "payin"
  }
}

Пример кода проверки подписи оповещений (Python3)

import json
import base64

from Crypto.Hash import SHA256
from Crypto.PublicKey import RSA
from Crypto.Signature.pkcs1_15 import PKCS115_SigScheme

from fastapi import FastAPI, Request, Response
from uvicorn import run


app = FastAPI()


pub_key_file_path = "./public.pem"
with open(pub_key_file_path, "rb") as f:
    encoded_pub_key = base64.urlsafe_b64encode(
        RSA.import_key(f.read()).export_key(),
    ).decode("utf-8")


def parse_json(prefix, obj, _result):
    if isinstance(obj, dict):
        for key, value in obj.items():
            new_prefix = f"{prefix}:{key}" if prefix else key
            parse_json(new_prefix, value, _result)
    elif isinstance(obj, list):
        for index, item in enumerate(obj):
            new_prefix = f"{prefix}:{index}"
            parse_json(new_prefix, item, _result)
    else:
        _result.append(f"{prefix}:{obj or 'None'}")


def normalize_message(_payload):
    _result = []
    parse_json("", _payload, _result)
    _result.sort()
    _joined_result = ";".join(_result)
    return _joined_result


@app.route("/callback", methods=["POST"])
async def validate_request(request: Request):
    _headers = request.headers
    body = await request.body()

    if not body:
        payload = {}
    else:
        payload = json.loads(body.decode("utf-8"))

    joined_result = normalize_message(payload).encode("utf-8")

    message = "{}{}".format(
        base64.urlsafe_b64encode(joined_result).decode("utf-8"),
        str(_headers.get("x-access-timestamp")),
    )

    if _headers.get("x-access-token") != encoded_pub_key:
        raise ValueError("Invalid public key")

    signature = _headers.get("x-access-signature")

    pub_key = base64.urlsafe_b64decode(encoded_pub_key.encode("utf-8"))
    pub_key_rsa = RSA.import_key(pub_key)
    hash_of_received = SHA256.new(message.encode("utf-8"))
    verifier = PKCS115_SigScheme(pub_key_rsa)

    try:
        base64_bytes = signature.encode("ascii")
        signature_bytes = base64.urlsafe_b64decode(base64_bytes)
        verifier.verify(hash_of_received, signature_bytes)
    except ValueError:
        raise ValueError("Invalid signature")

    return Response(status_code=200)


if __name__ == "__main__":
    run(app, host="0.0.0.0", port=8080)