Банковские переводы в Азербайджане

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

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

H2H

Платеж через API HighHelp на стороне мерчанта

Валюта

AZN

Азербайджанский манат

Страна

AZ

Азербайджан

Депозиты

Доступные методы оплаты:
- card-p2p
- phone-p2p

Выплаты

Доступные методы выплат:
- card-p2p
- phone-p2p

Оплата

Общие требования к интеграции P2P-оплат по API описаны в разделе Общие требования для P2P (H2H).

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

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

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

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

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

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

    • merchant_callback_url  — динамический URL для получения информативных оповещений, например об изменении промежуточных статусов заявки и реквизитах для оплаты P2P-заявки. Оповещения по финальным статусам отправляются на 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  — информация об оплате

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

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

    • currency  — код валюты, в которой оплачивает пользователь, в формате ISO 4217 alpha-3. Список кодов приведен в разделе Коды валют.
      (string) (regex: ^[A-Z]{3}$)

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

    • bank_symbol  — код банка, на который пользователь хочет выполнить перевод. Если параметр не передан, банк выбирается случайным образом. Список доступных банков можно получить по API /api/v1/payment/p2p/bank/available. Примеры банков приведены в разделе Банки для P2P. Использование параметра снижает конверсию в выдачу реквизитов, поэтому его рекомендуется задавать только при необходимости.
      (string) (<= 32 символа)

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

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

  • sender  — данные карты или телефона отправителя

    • pan  — номер карты отправителя.
      (string<pan>) (<= 32 символа)

    • phone  — номер телефона отправителя.
      (string) (<= 24 символа)
      (regex: ^\+7\d{10}$|^\+994\d{7,12}$)

    • bank_symbol  — код банка, с карты или счета которого пользователь будет оплачивать. Для получения кодов банков используйте API /api/v1/payment/p2p/bank/all. Если банка нет в списке, параметр можно не передавать.
      (string) (<= 32 символа)

    • card_holder  — имя отправителя, как на карте.
      (string) (<= 255 символа)
      (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЕРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)

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

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

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

    • first_name  — имя пользователя, выполняющего оплату.
      (string) (<= 255 символа)

    • last_name  — фамилия пользователя, выполняющего оплату.
      (string) (<= 255 символа)

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

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

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

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

    • browser  — название и версия браузера пользователя.
      (string) (<= 512 символа)

    • device_type  — тип устройства пользователя.
      (string) (<= 512 символа)

    • user_agent  — идентификационная строка клиентского приложения.
      (string) (<= 1024 символа)

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

Если данные об отправителе (sender) не передаются, необходимо указать "sender": {}. При значении "sender": null запрос будет отклонен.

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

curl https://api.hh-processing.com/api/v1/payment/p2p/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": "AZN-PAYMENT-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/success",
    "merchant_decline_callback_url": "https://your-domain.com/decline",
    "redirect_url": "https://your-domain.com/order/page"
  },
  "payment": {
    "method": "card-p2p",
    "amount": 150000,
    "currency": "AZN",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "sender": {
    "pan": "4850788018041726",
    "card_holder": "Erik Ackerman"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "John",
    "last_name": "Snow",
    "customer_type": "ftd",
    "country": "AZ",
    "language": "az",
    "email": "[email protected]",
    "browser": "Google Chrome v15.12",
    "device_type": "Iphone 15 Pro"
  }
}'

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

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

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

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

  • sub_status  — под-статус обработки платежа. Используется только для отдельных значений 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 символа)

Поля recipient_requisites и display_data в ответе API остаются пустыми до перехода заявки в статус processing:awaiting_confirm или processing:paid.

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

Данные для отображения в платежной инструкции

Перед выводом платежной инструкции необходимо получить данные для ее формирования. Возможны два подхода:

  • дождаться оповещения со статусом processing:awaiting_confirm на URL, указанный в параметре merchant_callback_url. В теле оповещения будут переданы данные для инструкции;

  • опрашивать метод https://api.hh-processing.com/api/v1/payment/p2p/payin/info с интервалом 15 секунд до тех пор, пока статус заявки не станет processing:awaiting_confirm. После этого в ответе будут доступны данные инструкции.

В теле оповещения или ответа необходимо получить поле display_data. Это массив объектов со следующими полями:

  • type  — тип объекта. Для P2P-платежей используется значение add_info;

  • title  — имя атрибута инструкции. Возможные значения:

    • recipient_card_holder  — полное имя держателя карты;

    • recipient_pan  — номер карты, на которую нужно выполнить перевод;

    • recipient_phone  — номер телефона, на который нужно выполнить перевод;

    • lifetime  — время жизни инструкции (заявки) в секундах;

    • valid_until  — момент, до которого инструкция действительна, в формате Unix Timestamp (UTC);

    • amount  — сумма перевода в дробных единицах; подробнее см. в разделе Коды валют;

    • currency  — код валюты в формате ISO 4217 alpha-3;

    • bank_name  — наименование банка получателя;

    • bank_country  — код страны банка получателя в формате ISO 3166-1 alpha-2; полный список кодов см. в разделе Коды стран;

    • confirm_url  — URL для отправки запроса при подтверждении факта оплаты пользователем;

    • reject_url  — URL для отправки запроса при отказе пользователя от оплаты;

  • data  — значение атрибута инструкции.

Пример фрагмента с платежной инструкцией:

"display_data": [
  {
    "type": "add_info",
    "title": "recipient_card_holder",
    "data": "John Snow"
  },
  {
    "type": "add_info",
    "title": "recipient_pan",
    "data": "4850777018041155"
  },
  {
    "type": "add_info",
    "title": "recipient_phone",
    "data": "+994909994433"
  },
  {
    "type": "add_info",
    "title": "lifetime",
    "data": 300
  },
  {
    "type": "add_info",
    "title": "valid_until",
    "data": 1721647251
  },
  {
    "type": "add_info",
    "title": "amount",
    "data": 10000
  },
  {
    "type": "add_info",
    "title": "currency",
    "data": "AZN"
  },
  {
    "type": "add_info",
    "title": "bank_name",
    "data": "m10-az"
  },
  {
    "type": "add_info",
    "title": "bank_country",
    "data": "AZ"
  },
  {
    "type": "add_info",
    "title": "confirm_url",
    "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm"
  },
  {
    "type": "add_info",
    "title": "reject_url",
    "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel"
  }
]

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

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

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

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

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

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

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

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

curl https://api.hh-processing.com/api/v1/payment/p2p/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": "AZN-PAYMENT-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": "AZN-PAYMENT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "AZN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "card-p2p",
    "payment_system": null,
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4850788018041726",
    "card_holder": "Khal Drogo",
    "bank_name": "m10-az",
    "bank_country": "AZ",
    "currency": "AZN"
  },
  "sender": {
    "pan_hidden": "48507****1726",
    "card_holder_hidden": "Erik****rman"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.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 передается фактическая сумма, а в old_amount  — исходная. При расхождении сумм требуется создать апелляцию через поддержку HighHelp.
      (integer) (1 <= X <= 10000000000000)

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

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

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

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

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

    • type  — тип операции, например payin; общий список типов см. в разделе Типы платежей.
      (string) (<= 32 символа)

  • recipient_requisites  — реквизиты, на которые ожидается перевод

    • pan  — номер карты или телефона получателя платежа.
      (string<pan>) (<= 4096 символа)

    • card_holder  — имя держателя карты (как на карте). В редких случаях может содержать техническое значение "--".
      (string) (<= 255 символа)

    • bank_name  — наименование банка получателя.
      (string) (<= 255 символа)

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

  • sender  — реквизиты отправителя (пользователя мерчанта)

    • pan_hidden  — маскированный номер карты или телефона отправителя.
      (string) (<= 32 символа)

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

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

    • form_url  — ссылка на платежную страницу с реквизитами и инструкцией.
      (string<https-url>) (<= 255 символа)

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

Поля recipient_requisites и display_data остаются пустыми до перехода заявки в статус processing:awaiting_confirm или processing:paid.

Отмена заявки

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel

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

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

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

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

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

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

curl https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel \
  -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": "AZN-PAYMENT-123456"
  }
}'

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

{
  "status": "decline",
  "sub_status": null,
  "status_description": "Canceled by client",
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYMENT-123456"
}

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

  • 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 символа)

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

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm

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

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

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

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

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

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

curl https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm \
  -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": "AZN-PAYMENT-123456"
  }
}'

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

{
  "status": "processing",
  "sub_status": "paid",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYMENT-123456"
}

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

  • 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 символа)

Статусы оплат

Типы операций и статусов описаны в разделе Типы операций и статусы.
Коды статусов и возможные значения status и sub_status приведены в разделе Коды статусов.

Статус Подстатус Описание Состояние платежа

error

Платеж не был выполнен из-за ошибки, возникшей при проверке запроса

Промежуточное состояние

processing

new

Проверяется корректность запроса перед началом обработки

Промежуточное состояние

requisites

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

Промежуточное состояние

awaiting_confirm

Ожидается подтверждение оплаты от клиента, так как реквизиты уже предоставлены

Промежуточное состояние

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": "AZN-PAYMENT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "payment_system": null,
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4850788018041726",
    "card_holder": "Khal Drogo",
    "bank_name": "m10-az",
    "bank_country": "AZ",
    "currency": "AZN"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  },
  "additional_info": {
    "display_data": [
      {
        "type": "add_info",
        "title": "recipient_card_holder",
        "data": "Khal Drogo"
      },
      {
        "type": "add_info",
        "title": "recipient_pan",
        "data": "4850788018041726"
      },
      {
        "type": "add_info",
        "title": "lifetime",
        "data": 300
      },
      {
        "type": "add_info",
        "title": "valid_until",
        "data": 1721647251
      },
      {
        "type": "add_info",
        "title": "amount",
        "data": 10000
      },
      {
        "type": "add_info",
        "title": "currency",
        "data": "AZN"
      },
      {
        "type": "add_info",
        "title": "bank_name",
        "data": "m10-az"
      },
      {
        "type": "add_info",
        "title": "bank_country",
        "data": "AZ"
      },
      {
        "type": "add_info",
        "title": "confirm_url",
        "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm"
      },
      {
        "type": "add_info",
        "title": "reject_url",
        "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel"
      }
    ]
  }
}

Реквизиты (recipient_requisites) и платежная инструкция (additional_info) включаются в оповещения только для статусов processing:awaiting_confirm и processing:paid.
Для остальных статусов поля могут иметь значение null, например "recipient_requisites": null, "additional_info": null.

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

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

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

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

Оповещение отправляется, если заявка завершилась неуспешно (например, финальный статус decline).

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

Выплата

Создание заявки на выплату

POST https://api.hh-processing.com/api/v1/payment/p2p/payout

Параметры тела запроса при создании 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 символа)

  • receiver  — данные получателя выплаты

    • pan  — номер карты получателя; обязательный параметр, если payment.method = "card-p2p".
      (string<pan>) (<= 32 символа)

    • phone  — номер телефона получателя; обязательный параметр, если payment.method = "phone-p2p".
      (string) (<= 24 символа)
      (regex: ^\+7\d{10}$|^\+994\d{7,12}$)

    • bank_code  — код банка получателя. Пример для "Сбербанка": 100000000111. Список кодов банков доступен по API /api/v1/bank/all.
      (string) (= 12 символов)
      (regex: ^\d{12}$)

    • card_holder  — имя держателя карты получателя, как на карте.
      (string) (<= 255 символа)
      (regex: ^[a-zA-Zа-яА-ЯёрстуфхцчшщъыьэюЕРСТУФХЦЧШЩЪЫЬЭЮҐґЇїІіЄє0-9\s\-.']{1,255}$)

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

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

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

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

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

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

  • customer  — информация о пользователе-отправителе (клиенте мерчанта)

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

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

    • first_name  — имя пользователя, получающего выплату.
      (string) (<= 255 символа)

    • last_name  — фамилия пользователя, получающего выплату.
      (string) (<= 255 символа)

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

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

    • browser  — название и версия браузера.
      (string) (<= 512 символа)

    • device_type  — тип устройства.
      (string) (<= 512 символа)

    • user_agent  — идентификационная строка клиентского приложения.
      (string) (<= 1024 символа)

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

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

curl https://api.hh-processing.com/api/v1/payment/p2p/payout \
  -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": "AZN-PAYOUT-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/success",
    "merchant_decline_callback_url": "https://your-domain.com/decline"
  },
  "receiver": {
    "pan": "4850788018041726",
    "card_holder": "Erik Ackerman"
  },
  "payment": {
    "method": "card-p2p",
    "amount": 100,
    "currency": "AZN",
    "description": "Comment about the payout",
    "extra_param": "example"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "John",
    "last_name": "Snow",
    "country": "RU",
    "email": "[email protected]",
    "browser": "Google Chrome v15.12",
    "device_type": "Iphone 15 Pro"
  }
}'

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

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYOUT-123456"
}

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

  • 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 символа)

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

Информация о заявке на выплату

POST https://api.hh-processing.com/api/v1/payment/p2p/payout/info

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

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

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

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

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

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

curl https://api.hh-processing.com/api/v1/payment/p2p/payout/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": "AZN-PAYOUT-123456"
  }
}'

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

{
  "status": "processing",
  "sub_status": "payout_process",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYOUT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "AZN",
    "method": "card-p2p",
    "type": "payout"
  }
}

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

  • 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  — сумма заявки до апелляции. При расхождении с фактической суммой требуется апелляция через поддержку HighHelp.
      (integer) (1 <= X <= 10000000000000)

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

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

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

    • type  — тип операции, например payout; список типов приведен в Типы платежей.
      (string) (<= 32 символа)

Статусы выплат

Типы операций и статусов описаны в разделе Типы операций и статусы.
Коды статусов и возможные значения status и sub_status приведены в разделе Коды статусов.

Статус Под-статус Описание Состояние платежа

error

Выплата отклонена из-за ошибки, возникшей при проверке запроса.

Промежуточное состояние

processing

new

Проверка запроса перед обработкой.

Промежуточное состояние

requisites

Подбор трейдера, который исполнит выплату.

Промежуточное состояние

payout_process

Выполнение выплаты по указанным реквизитам.

Промежуточное состояние

dispute

incorrect_requisites

Трейдер сообщил о некорректных реквизитах выплаты.

Промежуточное состояние

payout_failed

Трейдер не смог выполнить выплату на корректные реквизиты.

Промежуточное состояние

payout_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:payout_process:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "AZN-PAYOUT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  },
  "additional_info": {}
}

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

Оповещение отправляется при успешной выплате (статус success).

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "AZN-PAYOUT-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  }
}

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

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

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "AZN-PAYOUT-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  }
}