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

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

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

H2H

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

Валюта

NGN

Нигерийская найра

Страна

NG

Нигерия

Депозиты

Доступные методы оплаты:
- wallet-link
- account-number
- ussd

Выплаты

Доступные методы выплат:
- account-number

Оплата

Общие требования к интеграции 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  — время жизни заявки в секундах. Максимальное значение  — 15 минут. Если параметр не указан, используется значение по умолчанию 15 минут.
      (integer) (300 <= X <= 900)

    • bank_symbol  — код банка, на который пользователь выполнит перевод. Обязательный параметр, если payment.method = "account-number". Список доступных банков можно получить по API /api/v1/payment/p2p/bank/available.
      (string) (<= 32 символа)

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

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

  • sender  — данные платежного средства пользователя

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

    • phone  — номер телефона отправителя. Обязательный параметр, если payment.method = "ussd".
      (string) (<= 24 символа)
      (regex: ^\d{8,15}$)

    • bank_symbol  — код банка, с карты или счета которого пользователь будет оплачивать. Обязательный параметр, если payment.method = "ussd" или payment.method = "wallet-link". Для получения кодов банков используйте 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 символа)

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

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

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": "NGN-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": "ussd",
    "amount": 150000,
    "currency": "NGN",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "sender": {
    "phone": "08012345678",
    "bank_symbol": "fidelity-bank-ngn"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "John",
    "last_name": "Snow",
    "customer_type": "ftd",
    "country": "NG",
    "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": "NGN-PAYMENT-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  }
}

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

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

Поля 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": "*901*000*7713#"
  },
  {
    "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": "NGN"
  },
  {
    "type": "add_info",
    "title": "bank_country",
    "data": "NG"
  },
  {
    "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": "NGN-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": "NGN-PAYMENT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "NGN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "ussd",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "*901*000*7713#",
    "card_holder": "---",
    "bank_country": "NG",
    "currency": "NGN"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  }
}

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

  • status  — статус обработки оплаты; коды статусов и значения status и sub_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  — время жизни заявки в секундах (не более 15 минут).
      (integer) (300 <= X <= 900)

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

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

    • payment_system  — платежная система.
      (string) (<= 32 символа)

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

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

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

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

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

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

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

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

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

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

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

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

Типы операций и статусов описаны в разделе Типы операций и статусы.
Коды статусов и возможные значения 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": "NGN-PAYMENT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "NGN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "ussd",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "*901*000*7713#",
    "card_holder": "Khal Drogo",
    "bank_name": "fidelity-bank-ngn",
    "bank_country": "NG",
    "currency": "NGN"
  },
  "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": "*901*000*7713#"
      },
      {
        "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": "NGN"
      },
      {
        "type": "add_info",
        "title": "bank_name",
        "data": "fidelity-bank-ngn"
      },
      {
        "type": "add_info",
        "title": "bank_country",
        "data": "NG"
      },
      {
        "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": "NGN-PAYMENT-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 700000,
    "old_amount": 500000,
    "initial_amount": 300000,
    "currency": "NGN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "ussd",
    "type": "payin"
  }
}

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

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

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "NGN-PAYMENT-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 700000,
    "old_amount": 700000,
    "initial_amount": 300000,
    "currency": "NGN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "ussd",
    "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 = "account-number".
      (string)
      (regex: ^\d{8,20}$)

    • bank_code  — код банка получателя. Обязательный параметр, если payment.method = "account-number". Список кодов банков можно получить по 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": "PAYOUT-NGN-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"
  },
  "receiver": {
    "pan": "012345678901",
    "bank_code": "930000000007",
    "card_holder": "John Snow"
  },
  "payment": {
    "method": "account-number",
    "amount": 2000000,
    "currency": "NGN",
    "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": "NG",
    "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": "PAYOUT-NGN-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/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": "PAYOUT-NGN-PAYMENT-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": "PAYOUT-NGN-PAYMENT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "NGN",
    "method": "account-number",
    "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": "PAYOUT-NGN-PAYMENT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "NGN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "account-number",
    "type": "payout"
  },
  "additional_info": {}
}

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

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

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

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

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

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "PAYOUT-NGN-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": "NGN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "account-number",
    "type": "payout"
  }
}