Quick start

This section describes a minimal integration scenario for making the first payment in a test environment via the H2H API.

Result of script execution

After completing the steps in this section, you:

  • create a test cash register and receive a pair of keys for signing requests;

  • send a request to create a P2P payment in a test environment;

  • receive an API response and an HTTP notification (callback) about the processing result.

For a detailed description of the authentication and request signing mechanism, seeAuthentication and Signature.

Prerequisites

To complete the steps in this section you will need:

  • access to the merchant's account;

  • The cash register has passed verification and has the statusConfirmed;

  • cash register encryption keys have been received;

  • installedcurlor another HTTP client;

  • ability to send HTTPS requests tohttps://api.hh-processing.com.

Gaining access to your account, creating a cash register and generating keys are described in the sectionAuthentication and Signature.

Step 1. Prepare authentication parameters

For each request to the API, you need to generate headers:

  • x-access-timestamp— request generation time in Unix Timestamp (UTC) format in seconds.

  • x-access-merchant-id- cash register identifier (valueUUID, obtained during key generation).

  • x-access-token— public key of the cash register, encoded in Base64Url format.

  • x-access-signature— digital signature of the messagesha256(base64url(body) + timestamp), generated by the cash register’s private key.

The signature generation algorithm and code examples are given inAuthentication and Signature.

For the examples below, the following test values ​​are used:

  • PROJECT_ID- cash register identifier, for example57aff4db-b45d-42bf-bc5f-b7a499a01782.

  • API_KEY— header meaningx-access-token.

  • SIGNATURE— header meaningx-access-signature.

  • TIMESTAMP— header meaningx-access-timestamp.

Step 2. Create a test P2P payment

In this example, an application for P2P payment by card is created in a test environment.

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

Request body (minimum set of fields):

{
  "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"
  },
  "sender": {},
  "customer": {
    "id": "test-user-1",
    "ip_address": "203.0.113.10",
    "country": "RU"
  }
}

  • amountindicated in fractional currency units (in the example10000= 100.00 RUB). See section for detailsCurrency codes.

Example request usingcurl:

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"
    },
    "sender": {},
    "customer": {
      "id": "test-user-1",
      "ip_address": "203.0.113.10",
      "country": "RU"
    }
  }'

Example of a successful response:

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

The list of statuses and substatuses is described in the sectionStatus codes.

Step 3: Process the result alert

After changing the status of the application, the system sends an HTTP request to one of the URLs specified in the fieldgeneral:

  • merchant_callback_url— informative alerts on intermediate statuses.

  • merchant_success_callback_url— notifications about successful completion.

  • merchant_decline_callback_url— notifications about unsuccessful completion.

Example of a successful notification:

{
  "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,
    "old_amount": 10000,
    "initial_amount": 10000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payin"
  }
}

Recommended:

  • check the digital signature of the notification using the algorithm described inAuthentication and Signature;

  • implement protection against repeated processing of duplicate alerts (for example, use an idempotency keyproject_id:payment_id:status:sub_status).

Step 4. Check application status via API

If the alert was not processed or you need to explicitly check the status of the ticket, you can query its status using a separate API method.

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

Example request:

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"
    }
  }'

The response contains the current valuesstatus, sub_status, as well as blockspayment_infoand other fields similar to the fields from alerts.

Test P2P payment processing scheme

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

Next steps