Дополнительные API ручки

Получить список банков¶

Данный API запрос возвращает список банков, символы (symbol) которых необходимо использовать при создании заявок как на оплату, так и на выплату.

POST https://api.hh-processing.com/api/v1/bank/all

Параметры, которые необходимо отправить в теле запроса.

general** - информация по заявке
- project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
  (string) (<= 32 символа)

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

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

curl https://api.hh-processing.com/api/v1/bank/all \
-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"
  }
}'

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

[
  {
    "id": "607714dd-8cd0-4e9d-82c2-0079a13ce0e1",
    "name": "Сбербанк",
    "symbol": "sberbank",
    "sbp_code": "100000000111",
    "is_sbp_bank": true,
    "country_code": "RU"
  },
  {
    "id": "9fb71ff0-0252-4d81-9eeb-229b8c91347a",
    "name": "Свой банк",
    "symbol": "svoi-bank",
    "sbp_code": "990000000003",
    "is_sbp_bank": false,
    "country_code": "RU"
  }
]

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

id** - id банка.
(string) (<= 32 символа)
name** - имя банка.
(string) (<= 64 символа)
symbol** - символ банка. Используется для создания заявок.
(string) (<= 64 символа)
sbp_code** - код банка в системе быстрых платежей.
(string) (<= 12 символов)
(regex: ^\d{12}$)
is_sbp_bank** - является ли банк участником системы быстрых платежей.
(boolean)
country_code** - код страны в формате "ISO 3166-1 alpha-2". (string) (regex: ^[A-Z]{2}$)

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

Если банк не является участником системы быстрых платежей (is_sbp_bank=false), то его нельзя использовать для создания заявок на выплату по методу sbp-p2p

Коды валют¶

В следующей таблице приведена информация о валютах. Для каждой валюты приведены: код валюты в соответствии со стандартом ISO 4217 alpha-3, количество разрядов дробных единиц, название валюты и страна (или страны), где она используется.

Обычно с запросах сумма платежа указывается в дробных единицах валюты без десятичной точки и пробелов. Например, сумма 100 RUB представляется как 10000 (то есть 10000 копеек).

Но если у валюты нет дробных единиц — то есть значение в столбце "Количество разрядов дробных единиц" равно нулю, то в запросах сумму следует указывать в основных единицах валюты. Например, сумма 100 JPY представляется как 100.

Код	Количество разрядов дробных единиц	Валюта	Страна
ARS	2	Аргентинский песо	Аргентинская Республика
KZT	2	Казахстанский тенге	Республика Казахстан
RUB	2	Российский рубль	Российская Федерация
UZS	2	Узбекский сум	Республика Узбекистан
KRW	0	Южнокорейская вона	Республика Корея

Коды языков¶

В следующей таблице приведена информация о поддерживаемых языках на платежной странице (виджете). Для каждого языка приведён пример: код языка в соответствии со стандартом ISO 639-1 и название языка.

Код	Название яызка (ISO)	Эндоним
en	English	English
es	Spanish	Español
kk	Kazakh	Қазақша
ru	Russian	Русский язык
uz	Uzbek	Ózbekça

Коды стран¶

В следующей таблице приведена информация о поддерживаемых странах. Для каждой страны приведены: код страны в соответствии со стандартом ISO 3166-1 alpha-2, название страны и код языка, который отображается на платежной странице по умолчанию.

Код	Название страны	Код языка
AR	Аргентинская Республика	es
KZ	Республика Казахстан	kk
RU	Российская Федерация	ru
UZ	Республика Узбекистан	uz
KR	Республика Корея	ko

Коды статусов¶

В каждом оповещении (callback) есть блок полей, которые описывают статус заявки. В случае ошибок (error / decline), либо в случаях, когда требуется вмешательство мерчанта (dispute), заполняется поле status_description. Ниже приведён список значений, которые могут передаваться в описании статуса.

Ниже приведены популярные коды ошибок. Коды могут дополняться новыми, но существующие изменены быть не могут.

Статус	status_description	Описание
`decline`	Canceled by client	Клиент отменил платёж
`decline`	Declined by anti-fraud	Антифрод не пропустил заявку. Причины уточняйте у менеджера
`decline`	Requisites not found	Не удалось найти реквизиты для оплаты

Поддерживаемые платежные методы¶

Используйте данные методы при создании заявок при H2H-интеграции. Методы указываются в поле payment:method.

Символ	Описание	Доступные гео
`card-p2p`	P2P-перевод по номеру карты.	`ru`, `uz`, `az`, `kg`, `tj`
`sbp-p2p`	P2P-перевод по номеру телефона.	`ru`
`phone-p2p`	P2P-перевод по номеру телефона.	`kg`
`mobile-p2p`	P2P-перевод через мобильное приложение банка.	`ru`
`international-p2p`	P2P-перевод на реквизиты дружественных стран.	`ru`
`international-card-p2p`	P2P-перевод на карты иностранных банков.	`ru`, `kz`
`qr-link-p2p`	P2P-перевод по QR-ссылке.	`ru`, `kg`
`account-number`	P2P-перевод на номер счета.	`ar`, `kr`, `ng`, `ru`
`sbp-qr`	Перевод по QR-коду в системе быстрых платежей.	`ru`
`card-ecom`	Операции e-commerce.	`kz`, `uz`, `ru`
`mobile-money`	Перевод через мобильные деньги (Mobile Money).	`ke`
`eft-link`	Перевод через электронный банковский перевод (EFT).	`za`
`ussd`	Перевод через USSD-код.	`ng`
`wallet-link`	Перевод через электронный кошелек.	`ng`

Поддерживаемые методы платежной страницы¶

Используйте данные методы при создании заявок при H2C-интеграции. Методы указываются в поле payment:widget_method.

Символ	Описание	Доступные гео
`payin-p2p-card`	Метод для предвыбора оплаты по номеру карты.	`ru`, `uz`, `az`, `kg`, `tj`
`payin-account-number`	Метод для предвыбора оплаты по номеру банковского счёта.	`ng`, `ru`
`payin-p2p-phone`	Метод для предвыбора оплаты по номеру телефона.	`kg`
`payin-p2p-sbp`	Метод для предвыбора оплаты по номеру телефона.	`ru`
`payin-1-click`	Метод для предвыбора оплаты в один клик.	`ru`
`payin-p2p-international`	Метод для предвыбора оплаты на реквизиты дружественных стран.	`ru`
`payin-p2p-card-international`	Метод для предвыбора оплаты на карты иностранных банков.	`ru`, `kz`
`payin-p2p-mobile`	Метод для предвыбора оплаты через мобильное приложение банка.	`ru`
`payin-qr-link-p2p`	Метод для предвыбора оплаты по QR-ссылке.	`ru`, `kg`
`payin-qr-sbp`	Метод для предвыбора оплаты по QR-коду в системе быстрых платежей.	`ru`
`payin-ecom-card`	Метод для предвыбора e-commerce-оплаты.	`kz`, `uz`, `ru`
`payin-mobile-money`	Метод для предвыбора оплаты через мобильные деньги (Mobile Money).	`ke`
`payin-eft-link`	Метод для предвыбора оплаты через электронный банковский перевод (EFT).	`za`
`payin-ussd`	Метод для предвыбора оплаты через USSD-код.	`ng`
`payin-wallet-link`	Метод для предвыбора оплаты через электронный кошелек.	`ng`

Поддерживаемые типы платежей¶

Символ	Описание
`payin`	Оплата (payin) - тип платежа, который подразумевает перечисление денежных средств со счёта пользователя на счет мерчанта.
`payout`	Выплата (payout) - тип платежа, который подразумевает перечисление денежных средств со счёта мерчанта на счёт пользователя.

Поддерживаемые банки для p2p оплат¶

Пример списка банков, по которым можно произвести оплату (payin) по методам card-p2p и sbp-p2p. Данный список является демонстрационным. Для получения актуального списка банков доступных вашей кассе, необходимо воспользоваться API: /api/v1/payment/p2p/bank/available

ID	Название	Символ
`607714dd-8cd0-4e9d-82c2-0079a13ce0e1`	Сбербанк	sberbank
`cd440fb7-a98d-4900-aa00-f00d1618e0cd`	T-Банк	t-bank
`d4ef4b8d-6410-40a2-8109-4180812c7266`	АЛЬФА-БАНК	alfa-bank
`8b8f734c-1707-462e-bd79-7c1964b0c834`	Райффайзенбанк	raiffeisenbank
`58c8f03e-84d0-4edd-ab4e-05e1eb695200`	Банк ВТБ	bankvtb

Поддерживаемые банки для предвыбора при оплате по клику¶

Список банков, которые можно предвыбрать. Если банк предвыбран, то пользователь на нашей форме повторно банк выбирать не будет.

Название	Символ	Гео
Сбербанк	sberbank	`ru`
T-Банк	t-bank	`ru`
АЛЬФА-БАНК	alfa-bank	`ru`
Банк ВТБ	bankvtb	`ru`

Поддерживаемые банки для предвыбора при транграничном переводе¶

Список банков, которые можно предвыбрать. Если банк предвыбран, то пользователь на нашей форме повторно банк выбирать не будет.

Название	Символ	Гео
Сбербанк	sberbank	`ru`
T-Банк	t-bank	`ru`

Вы также можете указать любой другой банк (из списка банков доступных по API: /api/v1/bank/all), но платежная инструкция по этим банкам может отсутствовать. А это зачастую приводит к снижению конверсии в оплату.