Быстрый старт

В этом разделе описан минимальный сценарий интеграции для выполнения первого платежа в тестовом окружении через H2H API.

Результат выполнения сценария

После выполнения шагов из этого раздела вы:

  • создадите тестовую кассу и получите пару ключей для подписи запросов;

  • отправите запрос на создание P2P-платежа в тестовом окружении;

  • получите ответ API и оповещение (колбек) о результате обработки.

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

Предварительные условия

Для выполнения шагов из этого раздела требуется:

  • доступ к кабинету мерчанта;

  • созданная и настроенная касса;

  • сгенерированная пара ключей RSA (private/public) для кассы;

  • установленный curl либо другой HTTP-клиент;

  • возможность отправлять HTTPS-запросы к https://api.hh-processing.com.

Получение доступа к кабинету, создание кассы и генерация ключей описаны в разделе Аутентификация и подпись.

Шаг 1. Подготовить параметры аутентификации

Для каждого запроса к API необходимо сформировать заголовки:

  • x-access-timestamp — время формирования запроса в формате Unix Timestamp (UTC) в секундах.

  • x-access-merchant-id — идентификатор кассы (значение UUID, полученное при генерации ключей).

  • x-access-token — публичный ключ кассы, закодированный в формате Base64Url.

  • x-access-signature — цифровая подпись сообщения sha256(base64url(body) + timestamp), сформированная приватным ключом кассы.

Алгоритм формирования подписи и примеры кода приведены в Аутентификация и подпись.

Для примеров ниже используются следующие тестовые значения:

  • PROJECT_ID — идентификатор кассы, например 57aff4db-b45d-42bf-bc5f-b7a499a01782.

  • API_KEY — значение заголовка x-access-token.

  • SIGNATURE — значение заголовка x-access-signature.

  • TIMESTAMP — значение заголовка x-access-timestamp.

Шаг 2. Создать тестовый P2P-платеж

В этом примере создается заявка на P2P-платеж по карте в тестовом окружении.

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

Тело запроса (минимальный набор полей):

{
  "general": {
    "project_id": "PROJECT_ID",
    "payment_id": "P2P-TEST-0001",
    "merchant_callback_url": "https://example.com/internal-callback",
    "merchant_success_callback_url": "https://example.com/payment-success",
    "merchant_decline_callback_url": "https://example.com/payment-decline"
  },
  "payment": {
    "method": "card-p2p",
    "amount": 10000,
    "currency": "RUB",
    "description": "Test P2P payment"
  },
  "sender": {
    "pan": "4242424242424242",
    "year": 2029,
    "month": 1,
    "card_holder": "TEST CARDHOLDER",
    "cvv": "123"
  },
  "receiver": {
    "pan": "4000000000000002"
  },
  "customer": {
    "id": "test-user-1",
    "ip_address": "203.0.113.10",
    "country": "RU"
  }
}

  • amount указывается в дробных единицах валюты (в примере 10000 = 100,00 RUB). Подробности см. в разделе Коды валют.

Пример запроса с использованием curl:

curl https://api.hh-processing.com/api/v1/payment/p2p/payin \
  -X POST \
  -H "x-access-timestamp: TIMESTAMP" \
  -H "x-access-merchant-id: PROJECT_ID" \
  -H "x-access-signature: SIGNATURE" \
  -H "x-access-token: API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "general": {
      "project_id": "PROJECT_ID",
      "payment_id": "P2P-TEST-0001",
      "merchant_callback_url": "https://example.com/internal-callback",
      "merchant_success_callback_url": "https://example.com/payment-success",
      "merchant_decline_callback_url": "https://example.com/payment-decline"
    },
    "payment": {
      "method": "card-p2p",
      "amount": 10000,
      "currency": "RUB",
      "description": "Test P2P payment"
    },
    "sender": {
      "pan": "4242424242424242",
      "year": 2029,
      "month": 1,
      "card_holder": "TEST CARDHOLDER",
      "cvv": "123"
    },
    "receiver": {
      "pan": "4000000000000002"
    },
    "customer": {
      "id": "test-user-1",
      "ip_address": "203.0.113.10",
      "country": "RU"
    }
  }'

Пример успешного ответа:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "PROJECT_ID",
  "payment_id": "P2P-TEST-0001"
}

Список статусов и подстатусов описан в разделе Коды статусов.

Шаг 3. Обработать оповещение о результате

После изменения статуса заявки система отправляет HTTP-запрос на один из URL, указанных в поле general:

  • merchant_callback_url — информативные оповещения по промежуточным статусам.

  • merchant_success_callback_url — оповещения об успешном завершении.

  • merchant_decline_callback_url — оповещения о неуспешном завершении.

Пример успешного оповещения:

{
  "project_id": "PROJECT_ID",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "P2P-TEST-0001"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "currency": "RUB",
    "method": "card-p2p",
    "type": "payin"
  }
}

Рекомендуется:

  • проверять цифровую подпись оповещения по алгоритму, описанному в Аутентификация и подпись;

  • реализовать защиту от повторной обработки дубликатов оповещений (например, использовать ключ идемпотентности project_id:payment_id:status:sub_status).

Шаг 4. Проверить статус заявки через API

Если оповещение не было обработано или требуется явная проверка состояния заявки, можно запросить ее статус с помощью отдельного метода API.

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

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

curl https://api.hh-processing.com/api/v1/payment/p2p/payin/info \
  -X POST \
  -H "x-access-timestamp: TIMESTAMP" \
  -H "x-access-merchant-id: PROJECT_ID" \
  -H "x-access-signature: SIGNATURE" \
  -H "x-access-token: API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "general": {
      "project_id": "PROJECT_ID",
      "payment_id": "P2P-TEST-0001"
    }
  }'

Ответ содержит текущие значения status, sub_status, а также блоки payment_info и другие поля, аналогичные полям из оповещений.

Схема обработки тестового P2P-платежа

sequenceDiagram
    autonumber

    participant User as Пользователь
    participant Merchant as Бэкенд мерчанта
    participant HH as HighHelp API
    participant Provider as Платежный провайдер/банк
    participant Callback as Endpoint оповещений мерчанта

    User->>Merchant: Инициирует P2P-платеж
    Merchant->>HH: POST /api/v1/payment/p2p/payin - (тело запроса + заголовки аутентификации)
    HH->>HH: Проверка подписи и параметров заявки
    HH->>Provider: Маршрутизация и передача заявки провайдеру
    Provider-->>HH: Результат обработки заявки
    HH-->>Merchant: HTTP 200 - {"status": "processing", "sub_status": "new", ...}

    HH-->>Callback: оповещение о смене статуса - (success / decline / error / processing:*)
    Callback-->>HH: HTTP 200 OK

    alt оповещение не получено или требуется явная проверка статуса
        Merchant->>HH: POST /api/v1/payment/p2p/payin/info - (project_id, payment_id)
        HH-->>Merchant: Текущий статус и детали заявки
    end

Следующие шаги