Банковские переводы в России
| Название | Код | Описание |
|---|---|---|
Тип интеграции |
|
Платеж через платежный виджет HighHelp |
Валюта |
|
Российский рубль |
Страна |
|
Российская Федерация |
Депозиты |
✅ |
Доступные методы для оплаты: |
Выплаты |
❌ |
Выплаты недоступны |
Оплата
Создание заявки
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 символа)
-
|
Поля, помеченные , являются обязательными. |
Статусы платежей
Полный перечень статусов и подстатусов см. в разделе Статусы операций и коды ошибок.
| Статус | Подстатус | Описание | Действия мерчанта |
|---|---|---|---|
|
Запрос отклонен из-за ошибки, связанной с параметрами платежа. |
Обратитесь в поддержку |
|
|
|
Платеж создан и ожидает действий клиента. |
Действия не требуются |
|
Требуется ввод реквизитов, доступна ссылка на форму в |
Направьте клиента на форму оплаты |
|
|
Ожидается подтверждение оплаты клиентом. Возможна оплата через перенаправление или QR. |
Дождитесь завершения оплаты |
|
|
Средства зафиксированы и ожидается финальное подтверждение. |
Дождитесь завершения оплаты |
|
|
|
Клиент не выполнил оплату в течение времени жизни платежа ( |
Действия не требуются |
|
Получена сумма, не совпадающая с заявленной. |
Обратитесь в поддержку |
|
|
Время ожидания подтверждения истекло, оплата не завершена. |
Обратитесь в поддержку |
|
|
Платеж отклонен. |
Сообщите клиенту об отказе |
|
|
Платеж успешно подтвержден. |
Действия не требуются |
Оповещения
|
Рекомендуется реализовать проверку входящих оповещений на дубликаты. Ключ идемпотентности можно формировать по шаблону |
|
Каждое оповещение подписывается цифровой подписью 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"
}
}
|
Замаскированные реквизиты в блоке |
Успешные оповещения
Оповещение отправляется, если заявка завершилась в статусе 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)