Перейти к содержанию

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

Название Код Описание
Тип интеграции H2H Платеж на вашей форме оплаты
Валюта NGN Нигерийская найра
Страна NG Федеративная Республика Нигерия
Депозиты ✅ Доступные методы для оплаты:
- wallet-link
- account-number
- ussd
Выплаты ✅ Доступные методы для выплаты:
- account-number

Оплата

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

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

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

  • general** - информация по заявке
    • project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
      (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 - cсылка для редиректа пользователя с формы оплаты после завершения платежа
      (string<https-url>) (<= 2048 символа)
  • payment** - информация по платежу
    • method** - код метода оплаты. Список методов находится в разделе "Поддерживаемые платежные методы".
      (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 - дополнительный параметр, используемый для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
      (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|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/sucess",
    "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": "KE",
    "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** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат"
    (string) (<= 32 символа)
  • sub_status - под-статус обработки платежа. Используется только для определенных статусов оплат. Список под-статусов можно посмотреть в разделе "Статусы оплат"
    (string) (<= 32 символа)
  • status_description - дополнительная информация по статусу. Используется в случае, если оплата не прошла, либо произошла ошибка
    (string) (<= 1024 символа)
  • request_id** - идентификатор платежа, который генерируется в нашей платежной системе
    (string) (<= 32 символа)
  • project_id** - идентификатор кассы, полученный от HH в процессе интеграции
    (string) (<= 32 символа)
  • payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта
    (string) (<= 255 символа)
  • integration - дополнительная мета информация по платежу
    • form_url** - ссылка на платежную страницу, на которую можно пере-адресовать пользователя. На платежной странице отображаются реквизиты для оплаты, платёжная инструкция и другая информация необходимая для платежа.
      (string<https-url>) (<= 255 символа)
    • redirect_url - cсылка для редиректа пользователя с формы оплаты после завершения платежа
      (string<https-url>) (<= 2048 символа)

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

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

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

Перед тем, как отобразить платежную инструкцию, вам необходимо её получить. Способы получения описаны ниже.

  • Дождаться колбэка со статусом processing:awaiting_confirm на URL указанный в параметре merchant_callback_url. В теле ответа будут содержаться данные для отображения платежной инструкции.
  • Альтернативным способом является простук раз в 15 секунд по URL https://api.hh-processing.com/api/v1/payment/p2p/payin/info. Как только статус заявки сменится на 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 - код страны банка получателя перевода;
    • 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** - идентификатор кассы, полученный от HH в процессе интеграции.
      (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** - статус обработки оплаты. Список статусов можно посмотреть в разделе "Статусы оплат"
    (string) (<= 32 символа)
  • sub_status - под-статус обработки платежа. Используется только для определенных статусов оплат. Список под-статусов можно посмотреть в разделе "Статусы оплат"
    (string) (<= 32 символа)
  • status_description - дополнительная информация по статусу. Используется в случае, если оплата не прошла, либо произошла ошибка
    (string) (<= 1024 символа)
  • request_id** - идентификатор платежа, который генерируется в нашей платежной системе
    (string) (<= 32 символа)
  • project_id** - идентификатор кассы, полученный от HH в процессе интеграции
    (string) (<= 32 символа)
  • payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта
    (string) (<= 255 символа)
  • payment_info** - информация по оплате
    • amount** - сумма заявки. Сумма указывается в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют";
      (integer) (1 <= X <= 10000000000000)
    • old_amount** - сумма заявки до апелляции. Сумма может измениться, если заявка была создана на одну сумму, но пользователь перевёл другую сумму. В таком случае, в поле amount указывается фактическая сумма, полученная от пользователя (необходимо связаться с тех. поддержкой HH и решить апелляцию по заявке). А в поле old_amount указывается сумма, на которую был создана заявка изначально. Если сумма не менялась, то значения данных полей будут равны;
      (integer) (1 <= X <= 10000000000000)
    • initial_amount** - сумма, указанная при создании заявки. Значение данного поля остаётся неизменным
      (integer) (1 <= X <= 10000000000000)
    • currency** - код валюты, в которой оплачивает пользователь в формате "ISO-4217 alpha-3". Подробнее о кодах валют в разделе "Коды валют"
      (string) (regex: ^[A-Z]{3}$)
    • lifetime - время жизни заявки в секундах. Максимальное время жизни - 15 мин. Если время не указано, то устанавливается значение по умолчанию - 15 мин.
      (integer) (300 <= X <= 900)
    • expiration_date - время до которого заявка действительна, значение указывается в "Unix Timestamp (UTC)";.
      (integer) (X <= 2^32)
    • method** - метод оплаты, который был выбран при создании платежа. Подробнее о методах оплаты можно прочитать в разделе "Поддерживаемые платежные методы"
      (string) (<= 32 символа)
    • payment_system - платежная система.
      (string) (<= 32 символа)
    • type - тип оплаты, который был выбран при создании платежа. Подробнее о методах оплаты можно прочитать в разделе "Поддерживаемые типы платежей"
      (string) (<= 32 символа)
  • recipient_requisites - реквизиты, на которые ожидается оплата от пользователя:
    • pan** - номер телефона/карты, на который ожидается перевод от пользователя;
      (string<pan>) (<= 4096 символа)
    • card_holder** - имя держателя карты (в точности как написано на карте). В редких случаях, имя держателя карты может отсутствовать, в таких случаях вы данном поле будут приходить моковые значения такие как "---".
      (string) (<= 255 символа)
    • bank_name - наименование банка получателя перевода;
      (string) (<= 255 символа)
    • bank_country - код страны банка получателя перевода;
      (string) (regex: ^[A-Z]{2}$)
    • currency - код валюты оплаты в формате "ISO-4217 alpha-3";
      (string) (regex: ^[A-Z]{3}$)
  • integration - дополнительная мета информация по платежу
    • form_url** - ссылка на платежную страницу, на которую можно пере-адресовать пользователя. На платежной странице отображаются реквизиты для оплаты, платёжная инструкция и другая информация необходимая для платежа.
      (string<https-url>) (<= 255 символа)
    • redirect_url - cсылка для редиректа пользователя с формы оплаты после завершения платежа
      (string<https-url>) (<= 2048 символа)

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

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

Статус Под-статус Описание Состояние платежа
error Платеж не был осуществлен из-за ошибки, возникшей при проверке запроса Промежуточное состояние
processing new Проверка запроса перед непосредственной его обработкой Промежуточное состояние
requisites Подбор реквизитов, на которые клиенту будет необходимо перечислить указанную в запросе сумму Промежуточное состояние
awaiting_confirm Ожидание подтверждения оплаты от клиента, т.к. реквизиты ему уже были предоставлены Промежуточное состояние
paid Клиент подтвердил, что он отправил сумму на выданные реквизиты Промежуточное состояние
dispute no_payment Клиент не произвёл оплату по заявке, за время её жизни (lifetime) Промежуточное состояние
different_amount Клиент отправил неверную сумму Промежуточное состояние
confirm_timeout Время жизни заявки истекло, но клиент подтвердил оплату предоставив чек Промежуточное состояние
decline Платеж отклонен Финальное состояние
success Платеж проведен Финальное состояние

Оповещения (callback):

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

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

У p2p платежей есть 3 типа оповещений:

  • Информативные - оповещения по промежуточным статусам заявок. Оповещение отправляется, если у заявки меняется статус. URL для отправки оповещений указывается при создании заявки в параметре merchant_callback_url
  • Успешные - оповещения по успешным заявкам. Оповещение отравляется, если заявка завершена успешно. URL для отправки оповещений указывается при создании заявки в параметре merchant_success_callback_url
  • Неуспешные - оповещения по неуспешным заявкам. Оповещение отправляется, если в процессе обработки заявки возникла ошибка, либо время жизни заявки истекло. 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.
В случае, если статус заявки другой, то реквизиты не будут отправлены. Пример: "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

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

  • general** - информация по заявке
    • project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
      (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" (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** - код метода выплаты. Список методов находится в разделе "Поддерживаемые платежные методы".
      (string) (<= 32 символа)
    • amount** - сумма, которую необходимо отправить на указанные реквизиты. Сумму необходимо указывать в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют"
      (integer) (1 <= X <= 10000000000000)
    • currency** - валюта платежа в формате "ISO-4217 alpha-3". Подробнее о кодах валют в разделе "Коды валют"
      (string) (regex: ^[A-Z]{3}$)
    • description - описание платежа или комментарий. Данные будут отображены в личном кабинете мерчанта.
      (string) (<= 255 символа)
    • extra_param - дополнительный параметр, используемый для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
      (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/sucess",
    "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": "KE",
    "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** - идентификатор платежа, который генерируется в нашей платежной системе
    (string) (<= 32 символа)
  • project_id** - идентификатор кассы, полученный от HH в процессе интеграции
    (string) (<= 32 символа)
  • payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта
    (string) (<= 255 символа)

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

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

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

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

  • general** - информация по заявке
    • project_id** - идентификатор кассы, полученный от HH в процессе интеграции.
      (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** - идентификатор платежа, который генерируется в нашей платежной системе
    (string) (<= 32 символа)
  • project_id** - идентификатор кассы, полученный от HH в процессе интеграции
    (string) (<= 32 символа)
  • payment_id** - идентификатор платежа, уникальный в рамках кассы мерчанта
    (string) (<= 255 символа)
  • payment_info** - информация по оплате
    • amount** - сумма заявки. Сумма указывается в дробных единицах. Подробнее об этом можно прочитать в разделе "Коды валют";
      (integer) (1 <= X <= 10000000000000)
    • old_amount** - сумма заявки до апелляции. Сумма может измениться, если заявка была создана на одну сумму, но пользователь перевёл другую сумму. В таком случае, в поле amount указывается фактическая сумма, полученная от пользователя (необходимо связаться с тех. поддержкой HH и решить апелляцию по заявке). А в поле old_amount указывается сумма, на которую был создана заявка изначально. Если сумма не менялась, то значения данных полей будут равны;
      (integer) (1 <= X <= 10000000000000)
    • initial_amount** - сумма, указанная при создании заявки. Значение данного поля остаётся неизменным
      (integer) (1 <= X <= 10000000000000)
    • currency** - код валюты, в которой исполняется выплата в формате "ISO-4217 alpha-3". Подробнее о кодах валют в разделе "Коды валют"
      (string) (regex: ^[A-Z]{3}$)
    • method** - код метода оплаты. Список методов находится в разделе "Поддерживаемые платежные методы".
      (string) (<= 32 символа)
    • type - тип оплаты, который был выбран при создании платежа. Подробнее о методах оплаты можно прочитать в разделе "Поддерживаемые типы платежей"
      (string) (<= 32 символа)

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

Статус Под-статус Описание Состояние платежа
error Выплата не была осуществлена из-за ошибки, возникшей при проверке запроса Промежуточное состояние
processing new Проверка запроса перед непосредственной его обработкой Промежуточное состояние
requisites Подбор трейдера, который исполнит выплату Промежуточное состояние
payout_process Исполняется процесс выплаты по указанным реквизитам Промежуточное состояние
dispute incorrect_requisites Трейдер ответил нам тем, что полученные реквизиты выплаты неверные Промежуточное состояние
payout_failed Трейдеру не удалось выполнить выплату на верные реквизиты Промежуточное состояние
payout_timeout Заявка в системе помечается данным статусом в случае, если трейдер не исполнил выплату и время жизни заявки в системе истекло Промежуточное состояние
decline Операция отклонена Финальное состояние
success Операция выполнена Финальное состояние

Оповещения (callback):

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

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

У p2p выплат есть 3 типа оповещений:

  • Информативные - оповещения по промежуточным статусам заявок. Оповещение отправляется, если у заявки меняется статус. URL для отправки оповещений указывается при создании заявки в параметре merchant_callback_url
  • Успешные - оповещения по успешным заявкам. Оповещение отравляется, если заявка завершена успешно. URL для отправки оповещений указывается при создании заявки в параметре merchant_success_callback_url
  • Неуспешные - оповещения по неуспешным заявкам. Оповещение отправляется, если в процессе обработки заявки возникла ошибка, либо время жизни заявки истекло. 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"
  }
}