Банковские переводы в Таджикистане

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

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

H2C

Платеж через платежный виджет HighHelp

Валюта

TJS

Таджикский сомони

Страна

TJ

Республика Таджикистан

Депозиты

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

Выплаты

Выплаты недоступны

Оплата

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

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

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

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

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

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

    • widget_method — метод платежного виджета, который будет предвыбран на платежной странице. Поддерживаемые методы перечислены в разделе Методы виджета (H2C);
      (string) (<= 32 символа)

  • sender — информация о карте, телефоне или банке пользователя, с которых выполняется оплата

    • bank_symbol — банк, с которого клиент будет оплачивать заявку. Поддерживаемые значения перечислены в разделах Банки для предвыбора и Банки для P2P. Если нужного банка нет в списке или предвыбор банка не используются, параметр можно не передавать;
      (string) (<= 32 символа)

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

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

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

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

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

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

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

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

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

curl https://api.hh-processing.com/api/v1/widget/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": "PAYMENT-TJS-123456",
      "merchant_callback_url": "https://your-callback-domain.com/internal",
      "merchant_success_callback_url": "https://your-callback-domain.com/success",
      "merchant_decline_callback_url": "https://your-callback-domain.com/decline",
      "redirect_url": "https://your-web-site-url.com/order/page"
    },
    "payment": {
      "amount": 1500000,
      "currency": "TJS",
      "lifetime": 300,
      "description": "Comment about the payment",
      "extra_param": "example",
      "widget_method": "payin-p2p-card"
    },
    "sender": {
      "bank_symbol": "dushanbe-city-bank"
    },
    "customer": {
      "id": "random-customer-id",
      "ip_address": "1.1.1.1",
      "country": "TJ",
      "language": "tg",
      "customer_type": "ftd",
      "email": "[email protected]"
    }
  }'

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

{
  "status": "processing",
  "sub_status": "requisites",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "PAYMENT-TJS-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.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 символа)

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

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

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

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

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

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

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

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

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

curl https://api.hh-processing.com/api/v1/widget/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": "PAYMENT-TJS-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": "PAYMENT-TJS-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "TJS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.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, если пользователь перевел сумму, отличную от изначально указанной. В этом случае в amount передается фактическая сумма, а в old_amount — исходная сумма заявки;
      (integer) (1 <= X <= 10000000000000)

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

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

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

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

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

    • widget_method — метод платежного виджета, выбранный для оплаты. Поддерживаемые методы перечислены в разделе Методы виджета (H2C);
      (string) (<= 32 символа)

    • type — тип платежа. Поддерживаемые значения перечислены в разделе Типы платежей;
      (string) (<= 32 символа)

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

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

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

Статусы платежей

Полный перечень статусов и подстатусов см. в разделе Статусы операций и коды ошибок.

Статус Подстатус Описание Действия мерчанта

error

Запрос отклонен из-за ошибки, связанной с параметрами платежа.

Обратитесь в поддержку

processing

new

Платеж создан и ожидает действий клиента.

Действия не требуются

requisites

Требуется ввод реквизитов, доступна ссылка на форму в integration.form_url.

Направьте клиента на форму оплаты

awaiting_confirm

Ожидается подтверждение оплаты клиентом. Возможна оплата через перенаправление или QR.

Дождитесь завершения оплаты

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": "PAYMENT-TJS-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "TJS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan_hidden": "2202****6980",
    "card_holder_hidden": "Ко****ов",
    "bank_name": "dushanbe-city-bank",
    "bank_country": "TJ",
    "currency": "TJS"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Замаскированные реквизиты в блоке recipient_requisites передаются только для статусов processing:awaiting_confirm и processing:paid. Для остальных статусов заявки реквизиты не передаются (например, "recipient_requisites": null).

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

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

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

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

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

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