Kazakhstan (ECOM) — Payment

This section describes the mobile commerce payment scenario for Kazakhstan (KZ, KZT) with H2C integration via the HighHelp payment widget. When paying, the user receives a message from the provider's service with a code that he uses to confirm payment.

Name The code Description

Integration type

H2C

Payment via HighHelp payment widget

Currency

KZT

Kazakhstani tenge

Side

KZ

Republic of Kazakhstan

Deposits

✅

Available payment methods:
- payin-ecom-mobile

Supported carriers

Telecom operator The code

Beeline

BEELINE

Tele2

TELE2

Altel

ALTEL

Kcell

KCELL

Activ

ACTIV

Payment scenario

sequenceDiagram autonumber participant U as participant M as participant HH as HighHelp participant O as U->>M: M->>HH: HH-->>U: U->>HH: HH->>O: OTP- O-->>U: OTP- HH-->>U: OTP- U->>HH: OTP- HH->>O: OTP- O-->>HH: OTP- loop OTP- U->>HH: OTP- HH->>O: OTP- O-->>HH: OTP- O-->>U: OTP- U->>HH: OTP- HH->>O: OTP- O-->>HH: OTP- end HH-->>U:
Description of transitions

  1. The user initiates payment in the merchant's system.

  2. The merchant system sends a request to open a payment page in HighHelp.

  3. The HighHelp payment page is displayed to the user.

  4. The user selects a telecom operator and enters a phone number.

  5. The payment page requests an OTP code from the telecom operator.

  6. The telecom operator sends an OTP code to the user.

  7. The HighHelp payment page displays a form for the user to enter an OTP code.

  8. The user enters the OTP code on the payment page.

  9. The payment page sends the OTP code for verification.

  10. The payment page receives the OTP code verification result.

  11. The user performs a re-request for the OTP code after the re-request time has passed.

  12. The payment page requests a new OTP code from the telecom operator.

  13. The telecom operator confirms that a new OTP code has been requested.

  14. The telecom operator sends the user a new OTP code.

  15. The user re-enters the OTP code on the payment page.

  16. The payment page resends the OTP code for verification.

  17. The payment page receives the result of re-verification of the OTP code.

  18. The payment page displays the result to the user.

Creating an application

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

Request body parameters when creating a request.

  • general — information about the application.

    • project_id — cash ID issued by HighHelp during the integration process.
      (string) (<= 32)

    • payment_id — payment identifier, unique within the merchant’s checkout. You can use any letters, numbers and symbols in UTF-8 encoding.
      (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. 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. If no value is specified, it is used600.
      (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 consistent with HighHelp.
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

    • widget_method— code of the widget method that will be preselected on the payment page. For this scenario usepayin-ecom-mobile. See more details.Widget Methods (H2C).
      (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: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-MOBILE-ECOM-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-mobile"
    },
    "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": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Response options:

  • 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.

Application information

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

Parameters of the request body when receiving information about the application.

  • 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: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-MOBILE-ECOM-123456"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "awaiting_3ds_result",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-123456",
  "payment_info": {
    "amount": 1500000,
    "old_amount": 1500000,
    "initial_amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "method": "mobile-ecom",
    "widget_method": "payin-ecom-mobile",
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Response options:

  • 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 code. For this scenario the value ismobile-ecom.
      (string) (<= 32)

    • widget_method— payment page method code. For this scenario the value ispayin-ecom-mobile.
      (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: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-MOBILE-ECOM-123456"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-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: fe99035f86fa436181717b302b95bacff1' \
  -H 'x-access-token: fe99035f86fa436181717b302b95bacff1' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "KZT-MOBILE-ECOM-123456"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539fcb34ff5a3e286625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-MOBILE-ECOM-123456"
}

Payment statuses

A complete list of statuses and substatuses is given in the sectionStatus codes.

Status transition scheme

%%{init: {"flowchart": {"curve": "stepBefore"}} }%% flowchart LR R["processing:<br/>requisites"] A["processing:<br/>awaiting_3ds_result"] S["processing:<br/>sent_verification"] P["processing:<br/>paid"] I["processing:<br/>invalid_verification"] OK["success"] NO["decline"] R -->|OTP | A A -->|OTP <br/> | S S -->|OTP | P S -->|OTP | I I -->| OTP| S I -->| 3<br/> OTP| NO P -->| <br/> | OK P -->| <br/> | NO A -.->| <br/> | OK A -.->| <br/> | NO
Description of transitions

  1. processing:requisites → processing:awaiting_3ds_result— OTP requested from the user.

  2. processing:awaiting_3ds_result → processing:sent_verification— OTP has been sent for verification.

  3. processing:sent_verification → processing:paid— confirmation of the correctness of the OTP has been received.

  4. processing:sent_verification → processing:invalid_verification— invalid OTP received.

  5. processing:invalid_verification → processing:sent_verification— the user re-enters the OTP code, and the application returns to code verification.

  6. processing:invalid_verification → decline— after three incorrect attempts to enter the OTP code, the application is rejected.

  7. processing:paid → success— payment is successfully finalized.

  8. processing:paid → decline— payment is finalized by refusal.

  9. processing:awaiting_3ds_result → success— payment is completed successfully without a separate intermediate statusprocessing:paid.

  10. processing:awaiting_3ds_result → decline— payment ends in refusal without a separate intermediate statusprocessing:paid.

OTP Processing Rules

  • The user enters the OTP after the application has been transferred toprocessing:awaiting_3ds_result.

  • After sending the OTP, the application goes toprocessing:sent_verification.

  • If the OTP is correct, the application either goes toprocessing:paidfollowed by finalization, or is immediately finalized insuccessordecline.

  • If the OTP is incorrect, the application goes toprocessing:invalid_verification. The user can then re-enter the OTP code on the payment page. After three incorrect attempts to enter the OTP code, the application goes todecline.

  • After the current OTP expires, the user can request a new OTP code.

  • OTP- . It is determined by the payment script on the provider's side and is displayed to the user on the payment page.

  • The user can request a new OTP code up to three times. After the third repeated request, the application goes todecline.

  • After requesting a new OTP code again, the script continues waiting for a new OTP.

Status Substatus Description Merchant actions

processing

new

The application has been created and accepted for processing.

Wait for the transition to the next status.

requisites

The payment page accepted the phone number and ran the payment script.

Wait for the transition to the next status.

awaiting_3ds_result

OTP has been requested from the user.

Expect an informative alert atmerchant_callback_url.

sent_verification

OTP has been submitted for verification.

Wait for the next informative or final notification.

invalid_verification

The user sent an incorrect OTP. After three incorrect attempts to enter the OTP code, the application goes todecline.

Wait for the next informative or final notification.

paid

The operator confirmed the correctness of the OTP. Payment finalization is awaited.

Wait for the next informative or final notification.

success

Final successful completion of payment.

Record a successful payment in the merchant's system.

decline

Final refusal of payment.

Record the failure and inform the user of the result.

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": "16a10539fcb34ff5a3e286625a2dc3d3",
    "payment_id": "KZT-MOBILE-ECOM-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 1500000,
    "old_amount": 1500000,
    "initial_amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "mobile-ecom",
    "widget_method": "payin-ecom-mobile",
    "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": "16a10539fcb34ff5a3e286625a2dc3d3",
    "payment_id": "KZT-MOBILE-ECOM-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Payment general decline"
  },
  "payment_info": {
    "amount": 1500000,
    "old_amount": 1500000,
    "initial_amount": 1500000,
    "currency": "KZT",
    "lifetime": 600,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "mobile-ecom",
    "widget_method": "payin-ecom-mobile",
    "type": "payin"
  }
}