Bank cards (ECOM) — Payment

This section describes the scenario for accepting online payments by bank card through the HighHelp widget (integration type - H2C) using the method/api/v1/widget/payin.

Parameter The code Description

Integration type

H2C

Payment is made on the HighHelp payment page (widget).

Currency

Supported currencies:
KZT, UZS, RUB.
For a complete list of currencies, seeCurrency codes.

Deposits

✅

Available payment method:payin-ecom-card.

Creating an application

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

The following parameters are passed in the body of the request.

  • general — information about the application.

    • project_id — checkout ID obtained during integration with HighHelp.
      (string) (<= 32)

    • payment_id — payment identifier, unique within the merchant’s checkout. UTF-8 characters are allowed.
      (string) (<= 255)

    • merchant_callback_url— URL for informative alerts on intermediate statuses.
      (string<https-url>) (<= 2048)

    • merchant_success_callback_url— URL for notifications about successful payments.
      (string<https-url>) (<= 2048)

    • merchant_decline_callback_url— URL for notifications about unsuccessful payments.
      (string<https-url>) (<= 2048)

    • redirect_url— URL to which the user will be redirected from the payment page after completing the payment. If the parameter is not passed, the URL specified in the cash register settings is used.
      (string<https-url>) (<= 2048)

  • payment — payment information.

    • amount — payment amount in fractional currency units. For example,10000for the amount of 100.00. See more details.Currency codes.
      (integer) (1 <= X <= 10000000000000)

    • currency — currency code in ISO 4217 alpha-3 format.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds. Default is 600 seconds (maximum is 600 seconds).
      (integer) (300 <= X <= 600)

    • description— payment description or comment for display in the merchant’s account.
      (string) (<= 255)

    • extra_param— an additional parameter for individual routing of a request. The value is agreed with the administrator.
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

    • widget_method— widget method pre-selected in the widget. For a list of methods, seeWidget Methods.
      (string) (<= 32)

  • customer — information about the payer.

    • id — a unique user identifier in the merchant’s system.
      (string) (<= 255)

    • ip_address — User IP address.
      (string<ip-address>) (<= 255)

    • country — user country code in ISO 3166-1 alpha-2 format. For a list of countries, seeCountry codes.
      (string) (regex: ^[A-Z]{2}$)

    • language— widget interface language code in ISO 639-1 format. If no language is specified, the default language for the country is used. For a list of languages, seeLanguage codes.
      (string) (regex: ^[a-z]{2}$)

    • email— user email address.
      (string<email>) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/widget/payin \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: SIGNATURE' \
  -H 'x-access-token: API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-CARD-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": "KZT",
      "lifetime": 600,
      "description": "Comment about the payment",
      "extra_param": "example",
      "widget_method": "payin-ecom-card"
    },
    "customer": {
      "id": "cus_12345",
      "ip_address": "192.0.2.1",
      "country": "KZ",
      "language": "kk",
      "email": "customer@example.com"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-CARD-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Response fields:

  • status — payment processing status. For a list of statuses, see sectionsPayment statuses (payin)AndStatus codes.
    (string) (<= 32)

  • sub_status— payment processing substatus.
    (string) (<= 32)

  • status_description— text description of the status, including the reason for the failure or error.
    (string) (<= 1024)

  • request_id — application identifier in the HighHelp internal system.
    (string) (<= 32)

  • project_id — cashier identifier.
    (string) (<= 32)

  • payment_id — payment ID in the merchant’s system.
    (string) (<= 255)

  • integration— a block with parameters for integration.

    • form_url — URL of the payment page to which the user should be redirected.
      (string<https-url>) (<= 255)

    • redirect_url— URL to redirect the user after completing the payment.
      (string<https-url>) (<= 2048)

Fields marked, are mandatory.

Obtaining information about the application

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

Request:

  • general — information about the application.

    • project_id — cashier identifier.
      (string) (<= 32)

    • payment_id — payment ID.
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/widget/payin/info \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: SIGNATURE' \
  -H 'x-access-token: API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-CARD-123456"
    }
  }'

Sample answer:

{
  "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": "KZT-CARD-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 12000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "method": "card-ecom",
    "widget_method": "payin-ecom-card",
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Response fields:

  • status — the current status of payment processing.
    (string) (<= 32)

  • sub_status— current substatus of payment processing.
    (string) (<= 32)

  • status_description— text description of the status.
    (string) (<= 1024)

  • request_id — application identifier in the HighHelp internal system.
    (string) (<= 32)

  • project_id — cashier identifier.
    (string) (<= 32)

  • payment_id — payment ID in the merchant’s system.
    (string) (<= 255)

  • payment_info — payment information.

    • amount — the current amount of the application in fractional units.
      (integer) (1 <= X <= 10000000000000)

    • old_amount — the amount before changes as a result of processing or appeal. If the amount has not changed, the field valuesamountAndold_amountmatch.
      (integer) (1 <= X <= 10000000000000)

    • initial_amount — the amount specified when creating the application.
      (integer) (1 <= X <= 10000000000000)

    • currency — currency code in ISO 4217 alpha-3 format.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds.
      (integer) (300 <= X <= 600)

    • expiration_date— the moment until which the application is valid, in Unix Timestamp (UTC) format.
      (integer) (X <= 2^32)

    • method— payment method selected when processing the payment. For a list of methods, seePayment methods (H2H).
      (string) (<= 32)

    • widget_method— payment page method selected during payment.
      (string) (<= 32)

    • type— type of payment. Values ​​are described in sectionPayment types.
      (string) (<= 32)

  • integration— additional integration data.

    • form_url — URL of the payment page where the application is available.
      (string<https-url>) (<= 255)

    • redirect_url— URL for redirecting from the payment page after completing the payment.
      (string<https-url>) (<= 2048)

Payment confirmation

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

The method confirms payment for the application created through the widget.

Request:

  • general — information about the application.

    • project_id — cashier identifier.
      (string) (<= 32)

    • payment_id — payment ID in the merchant’s system.
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/widget/payin/confirm \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: SIGNATURE' \
  -H 'x-access-token: API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-CARD-123456"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-CARD-123456"
}

Cancellation of payment

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

The method cancels payment for an application created through the widget.

Request:

  • general — information about the application.

    • project_id — cashier identifier.
      (string) (<= 32)

    • payment_id — payment ID in the merchant’s system.
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/widget/payin/cancel \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: SIGNATURE' \
  -H 'x-access-token: API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-CARD-123456"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-CARD-123456"
}

Payment statuses

For payment by bank card through the widget, the statuses and transitions coincide with the life cycle of H2H payments. See sectionTypes of transactions and statuses of applications.
A complete list of status codes and descriptions is provided in the sectionStatus codes.

Status Alerts

General information

Alerts are sent to the URLs specified when the ticket was created:

  • merchant_callback_url— informative alerts on intermediate statuses.

  • merchant_success_callback_url— notifications about successful payments.

  • merchant_decline_callback_url— notifications about unsuccessful payments.

It is important to implement a check for duplicate alerts. It is recommended to use an idempotency key of the form{project_id}:{payment_id}:{status}:{sub_status}.
If a repeated notification with the same key is received, the merchant's system should ignore it to avoid double processing.

Each alert is digitally signed by HighHelp. The public key for verifying the signature can be obtained from your account. The keys differ for different cash registers.
The signature verification algorithm is the reverse of the request signature generation algorithm described in sectionAuthentication and Signature.

Informative Alerts

In the current version, informative alerts are not sent for payment by credit card via the widget.

Successful Alerts

An alert is sent if the application has received final statussuccess.

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

Unsuccessful Alerts

An alert is sent if the application has received final statusdecline.

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