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

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

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

H2H

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

Валюта

ARS

Аргентинский песо

Страна

AR

Аргентинская Республика

Депозиты

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

Выплаты

Доступные методы для выплаты:
- 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  — время жизни заявки в секундах. Максимальное значение  — 10 минут. Если параметр не указан, используется значение по умолчанию 10 минут.
      (integer) (300 <= X <= 600)

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

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

    • identification_data — данные идентификации пользователя. Поля не обязательны, но могут использоваться для повышения конверсии.

      • document_type — тип документа пользователя. Допустимые значения: CUIT, CUIL.
        (string) (regex: ^(CUIT|CUIL)$)

      • document_number — номер документа пользователя.
        (regex: ^\d{11}$)

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

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

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": "ARS-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": "account-number",
    "amount": 150000,
    "currency": "ARS",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "customer": {
    "id": "random-customer-id",
    "ip_address": "1.1.1.1",
    "first_name": "John",
    "last_name": "Snow",
    "customer_type": "ftd",
    "country": "AR",
    "email": "[email protected]",
    "browser": "Google Chrome v15.12",
    "device_type": "iPhone 15 Pro",
    "identification_data": {
      "document_type": "CUIT",
      "document_number": "01234567891"
    }
  }
}'

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

{
  "status": "processing",
  "sub_status": "requisites",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "ARS-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  — идентификатор платежа, который генерируется в платежной системе 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 остаются пустыми до тех пор, пока статус заявки не сменится на processing:awaiting_confirm или processing:paid.

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

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

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

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

В оповещении от системы HighHelp или в теле ответа необходимо найти поле 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": "0123456789012345678901"
  },
  {
    "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": "ARS"
  },
  {
    "type": "add_info",
    "title": "bank_name",
    "data": "naranja-x-ars"
  },
  {
    "type": "add_info",
    "title": "bank_country",
    "data": "AR"
  },
  {
    "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": "ARS-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": "ARS-PAYMENT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "ARS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "account-number",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4850788018041726",
    "card_holder": "Khal Drogo",
    "bank_name": "naranja-x-ars",
    "bank_country": "AR",
    "currency": "ARS"
  },
  "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 указывается фактическая полученная сумма (для урегулирования апелляции требуется обращение в техподдержку HighHelp), а в old_amount — исходная сумма. Если сумма не менялась, значения полей совпадают.
      (integer) (1 <= X <= 10000000000000)

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

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

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

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

    • method  — метод оплаты, выбранный при создании платежа. Список методов см. в разделе Платежные методы (H2H).
      (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 — код страны банка получателя перевода в формате 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": "ARS-PAYMENT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "ARS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "account-number",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4850788018041726",
    "card_holder": "Khal Drogo",
    "bank_name": "naranja-x-ars",
    "bank_country": "AR",
    "currency": "ARS"
  },
  "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": "ARS"
      },
      {
        "type": "add_info",
        "title": "bank_name",
        "data": "naranja-x-ars"
      },
      {
        "type": "add_info",
        "title": "bank_country",
        "data": "AR"
      },
      {
        "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": "ARS-PAYMENT-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 700000,
    "old_amount": 500000,
    "initial_amount": 300000,
    "currency": "ARS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "account-number",
    "type": "payin"
  }
}

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

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

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

Примеры кода

Пример кода на Python3 для приема оповещений и проверки цифровой подписи. Общий подход соответствует описанию в разделе Аутентификация и подпись запросов.

import json
import base64

from Crypto.Hash import SHA256
from Crypto.PublicKey import RSA
from Crypto.Signature.pkcs1_15 import PKCS115_SigScheme

from fastapi import FastAPI, Request, Response
from uvicorn import run


app = FastAPI()


pub_key_file_path = "./public.pem"
with open(pub_key_file_path, "rb") as f:
    encoded_pub_key = base64.urlsafe_b64encode(
        RSA.importKey(f.read()).export_key(),
    ).decode("utf-8")


def parse_json(prefix, obj, _result):
    if isinstance(obj, dict):
        for key, value in obj.items():
            new_prefix = f"{prefix}:{key}" if prefix else key
            parse_json(new_prefix, value, _result)
    elif isinstance(obj, list):
        for index, item in enumerate(obj):
            new_prefix = f"{prefix}:{index}"
            parse_json(new_prefix, item, _result)
    else:
        _result.append(f"{prefix}:{obj or 'None'}")


def normalize_message(_payload):
    _result = []
    parse_json("", _payload, _result)
    _result.sort()
    _joined_result = ";".join(_result)
    return _joined_result


@app.route("/callback", methods=["POST", "GET"])
async def validate_request(
    request: Request,
):
    _headers = request.headers
    body = await request.body()

    if not body:
        payload = {}
    else:
        payload = json.loads(body.decode("utf-8"))

    joined_result = normalize_message(payload).encode("utf-8")

    message = "{}{}".format(
        base64.urlsafe_b64encode(joined_result).decode("utf-8"),
        str(
            _headers.get("x-access-timestamp"),
        ),
    )

    if _headers.get("x-access-token") != encoded_pub_key:
        raise ValueError("Invalid public key")

    signature = _headers.get("x-access-signature")

    pub_key = base64.urlsafe_b64decode(
        encoded_pub_key.encode("utf-8"),
    )
    pub_key_rsa = RSA.importKey(pub_key)
    hash_of_received = SHA256.new(message.encode("utf-8"))
    verifier = PKCS115_SigScheme(pub_key_rsa)
    try:
        base64_bytes = signature.encode("ascii")
        signature_bytes = base64.urlsafe_b64decode(base64_bytes)
        verifier.verify(hash_of_received, signature_bytes)
    except ValueError:
        raise ValueError("Invalid signature")

    return Response(status_code=200)


if __name__ == "__main__":
    run(app, host="0.0.0.0", port=8080)

Выплата

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

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

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

  • 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".
      (regex: ^\d{22}$)

    • account_type — тип счета пользователя. Допустимые значения: CACC — расчетный счет, SVGS — сберегательный счет.
      (string) (regex: ^(CACC|SVGS)$)

  • 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 — дополнительный параметр для индивидуальной маршрутизации заявки. Настраивается совместно с администратором.
      (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 символа)

    • identification_data — данные идентификации пользователя.

      • document_type — тип документа пользователя. Допустимые значения: CUIT, CUIL.
        (string) (regex: ^(CUIT|CUIL)$)

      • document_number — номер документа пользователя.
        (regex: ^\d{11}$)

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

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

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-ARS-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": "0123456789012345678901",
    "account_type": "CACC"
  },
  "payment": {
    "method": "account-number",
    "amount": 2000000,
    "currency": "ARS",
    "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": "AR",
    "email": "[email protected]",
    "browser": "Google Chrome v15.12",
    "device_type": "iPhone 15 Pro",
    "identification_data": {
      "document_type": "CUIT",
      "document_number": "01234567891"
    }
  }
}'

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

{
  "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-ARS-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-ARS-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-ARS-PAYMENT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "ARS",
    "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  — сумма заявки до апелляции.
      (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 — тип операции. Список типов см. в разделе Поддерживаемые типы платежей.
      (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-ARS-PAYMENT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "ARS",
    "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-ARS-PAYMENT-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "ARS",
    "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-ARS-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": "ARS",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "account-number",
    "type": "payout"
  }
}