One-step Internet payment (ECOM H2H)

Name The code Description

Integration type

H2H

Payment via HighHelp API on the merchant side

Currency

Supported currencies:
- KZT
- UZS
- RUB

Deposits

Available payment methods:
- card-ecom

Payments

Available payment methods:
- card-ecom

Payment

Payment scheme

To make an Internet payment in one stage, the client explicitly transmits the card details. Other methods of transferring details will be available later.

The requirement for 3-D Secure authentication depends on the card issuer. The decision to carry out authentication is made by the issuer. It is not possible for the merchant to select a preferred authentication method.

3-D Secure can run in one of the following scenarios:

  • authentication without client participation (frictionless flow): the issuer only needs the data transmitted by the merchant when creating the payment; therefore, it is important to transmit all available information about the client (full name, browser information, etc.);

  • authentication with client actions (challenge flow): the client undergoes additional verification (confirmation code, biometrics, etc.), the authentication method is determined by the issuer.

Payment Process

  1. Creating an application.
    The merchant creates a payment request and transmits all the necessary data to make the payment.

  2. Receiving data for display in payment instructions.
    If the issuer requires 3-D Secure, the merchant receives an alert with the statusprocessing:awaiting_3ds_resultorprocessing:awaiting_redirect_result. The body of the alert contains data to redirect the client. For more details, see sectionClient redirection. If additional authentication is not required, the payment is finalized (point 6).

  3. Redirecting the client to the authentication page.
    The merchant redirects the client to the issuer’s page to complete 3-D Secure.

  4. Confirmation of payment from the issuer.
    If authentication is successful, the issuer sends data about the result. This data must be passed to the HighHelp API.

  5. Confirmation of payment from the merchant.
    If authentication is successful, the merchant confirms the payment in the HighHelp API. See section3DS authentication confirmation.

  6. Finalization of payment.
    Funds are debited from the client's card and credited to the merchant's account. The client is redirected to the merchant's page.

Below is a diagram of changing application statuses from creation to completion.

%%{ init: { "flowchart": { "curve": "linear" } } }%% flowchart TD start([ ]) NEW["<b>processing:new</b><br/> "] REQ["<b>processing:requisites</b><br/> "] A3DS["<b>processing:awaiting_3ds_result</b><br/> 3-D Secure"] AREDIR["<b>processing:awaiting_redirect_result</b><br/> "] SUCCESS["<b>success</b><br/> "] DECLINE["<b>decline</b><br/> "] start --> NEW NEW -->| | REQ NEW -->| <br/> | DECLINE REQ -->| . <br/> | SUCCESS REQ -->| 3-D Secure| A3DS REQ -->| <br/> | AREDIR REQ -->| <br/> | DECLINE A3DS -->|3-D Secure | AREDIR A3DS -->| 3-D Secure<br/> | DECLINE AREDIR -->| | SUCCESS AREDIR -->| <br/> | DECLINE

Creating an application

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

Parameters that must be sent in the body of the request when creating a payment.

  • general — information about the application.

    • project_id — ticket (project) identifier received from 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— dynamic URL for receiving informative notifications (changes in intermediate application statuses, etc.). Notifications regarding final statuses are sent to the URLs specified inmerchant_success_callback_urlAndmerchant_decline_callback_url.
      (string<https-url>) (<= 2048)

    • merchant_success_callback_url— dynamic URL to receive a notification when the operation is successful.
      (string<https-url>) (<= 2048)

    • merchant_decline_callback_url— dynamic URL to receive an alert if the operation is not successful.
      (string<https-url>) (<= 2048)

  • payment — payment information.

    • method — payment method code. A list of methods is given in the sectionPayment methods.
      (string) (<= 32)

    • amount — payment amount in fractional currency units. For more details, see sectionCurrency codes.
      (integer) (1 <= X <= 10000000000000)

    • currency — payment currency code in ISO-4217 alpha-3 format. For more information about currency codes, seeCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

    • description— payment description or comment. Displayed in the merchant's personal account.
      (string) (<= 255)

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

  • card — details of the client card from which funds are debited.

    • pan — customer card number.
      (string<pan>) (<= 32)

    • year — year of expiration of the client’s card.
      (integer) (2020 <= X <= 2099)

    • month — month of expiration of the client’s card.
      (integer) (1 <= X <= 12)

    • card_holder — cardholder’s name (as on the card).
      (string) (<= 255) (regex: ^[a-zA-Z - - ҐґЇїІіЄє0-9\s\-.']{1,255}$)

    • cvv— card authentication code (CVV/CVC).
      (string) (regex: ^\d{3,4}$)

  • customer — information about the client.

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

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

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

    • first_name— client’s name.
      (string) (<= 255)

    • last_name— last name of the client.
      (string) (<= 255)

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

    • email— client’s email address.
      (string<email>) (<= 255)

    • browser— name and version of the browser client.
      (string) (<= 512)

    • device_type— client device type.
      (string) (<= 512)

    • user_agent— identification string of the client application.
      (string) (<= 1024)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/ecom/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": "8b03432e-385b-4670-8d06-064591096795",
    "payment_id": "KZT-ECOM-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/success",
    "merchant_decline_callback_url": "https://your-domain.com/decline"
  },
  "payment": {
    "method": "card-ecom",
    "amount": 150000,
    "currency": "KZT",
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "card": {
    "pan": "4242242442422424",
    "year": 2029,
    "month": 1,
    "card_holder": "Alex Johnson",
    "cvv": "666"
  },
  "customer": {
    "id": "cus_12345",
    "ip_address": "192.0.2.1",
    "first_name": "Alex",
    "last_name": "Johnson",
    "country": "RU",
    "language": "ru",
    "email": "customer@example.com",
    "browser": "Google Chrome v15.12",
    "device_type": "iPhone 15 Pro",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
  }
}'

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-ECOM-123456"
}

Client redirection

If the issuer requires 3-D Secure, the merchant receives an alert with the statusprocessing:awaiting_3ds_resultorprocessing:awaiting_redirect_result. The notification body contains authentication data. An example of such a notification is given in the sectionInformative payment alerts.

Notifications are delivered with repeated attempts until successful delivery or until the request's lifetime expires. If the notification was not received and the application remains in interim status, you can request information about the application via the API. See sectionApplication information (payment).

3-D Secure Authentication

In an alert with statusprocessing:awaiting_3ds_resultin the fieldacs_infotransmitted:

  • pa_req— encrypted data with payment information for 3-D Secure.

  • acs_url— URL of the issuer’s page to which the client should be redirected.

  • md— data about the merchant’s application in the payment system.

After receiving the data, the merchant generates an HTML form and redirects the client to the issuer’s page for authentication.

<!DOCTYPE html>
<html>
<head>
    <title>3D Secure Authentication</title>
</head>
<body>

<form id="3dsform" action="{{acs_url}}" method="post" enctype="application/x-www-form-urlencoded">
    <input type="hidden" name="PaReq" value="{{pa_req}}"/>
    <input type="hidden" name="TermUrl" value="{{term_url}}"/>
    <input type="hidden" name="MD" value="{{md}}"/>
</form>

<script type="text/javascript">
    setTimeout(function () {
        document.getElementById("3dsform").submit();
    }, 1000);
</script>

</body>
</html>
  • {{acs_url}}— parameter valueacs_urlfrom the notification.

  • {{pa_req}}— parameter valuepa_reqfrom the notification.

  • {{term_url}}— your URL to which the issuer sends the authentication result in the formatFormData. Example:PaRes=ewogISsg2&MD=eyJwdXJ&Action=sendBy. After receiving the result, you need to pass the data to the HighHelp API. See section3DS authentication confirmation.

  • MD— parameter valuemdfrom the notification.

Authentication by client redirection

In an alert with statusprocessing:awaiting_redirect_resultin the fieldredirect_infotransmitted:

  • method— HTTP method for the request.

  • url— URL to which the client should be redirected.

  • body— data to be sent to the specified URL (can be empty).

After receiving the notification, the merchant redirects the client to the specified URL.

Application information

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

Parameters that must be sent in the body of the request to receive the statusecompayment requests.

  • general — information about the application.

    • project_id — checkout ID received from HighHelp during the integration process.
      (string) (<= 32)

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

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/ecom/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-ECOM-123456"
  }
}'

Sample answer:

{ "status": "processing", "sub_status": "awaiting_3ds_result", "status_description": null, "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3", "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782", "payment_id": "KZT-ECOM-123456", "payment_info": { "amount": 150000, "currency": "KZT", "lifetime": 300, "expiration_date": 1721647251, "updated_date": 1721647251, "created_date": 1721647251, "method": "card-ecom", "type": "payin" }, "card": { "pan": "424224******2424", "year": 2029, "month": 1, "card_holder": "Alex Johnson" }, "customer": { "id": "cus_12345" }, // `processing:awaiting_3ds_result` "acs_info": { "acs_url": "https://acs-url.com/order/1234", "pa_req": "123456789", "md": "V2hhdCdzIHVwIGR1ZGU=" } // `processing:awaiting_redirect_result` "redirect_info": { "method": "POST", "url": "https://bank-domain.com/redirect/1234", "body": { "key1": "value1", "key2": "value2" } } }

Response options:

  • status — payment processing status. The list of statuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • sub_status— payment processing substatus. Used only for individual statuses. The list of substatuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • status_description— additional information on status. Used if the payment did not go through or an error occurred.
    (string) (<= 1024)

  • request_id — payment identifier that is generated in the HighHelp system.
    (string) (<= 32)

  • project_id — checkout ID received from HighHelp during the integration process.
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s checkout.
    (string) (<= 255)

  • payment_info — payment information.

    • amount — payment amount in fractional currency units. For more details, see sectionCurrency codes.
      (integer) (1 <= X <= 10000000000000)

    • currency — currency code in ISO-4217 alpha-3 format. For more information about currency codes, seeCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime — request lifetime in seconds.
      (integer) (X <= 2^32)

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

    • created_date — time of creation of the application in Unix Timestamp (UTC) format.
      (integer) (X <= 2^32)

    • method — payment method code. The list of methods is given in the "Payment Methods" section.
      (string) (<= 32)

    • type — type of payment. For more information about types, seeSupported payment types.
      (string) (<= 32)

  • card — information about the card with which the payment is made.

    • pan — sender’s card number (masked).
      (string<pan>) (<= 32)

    • year — the year the card expires.
      (integer) (2020 <= X <= 2099)

    • month — month of card expiration date.
      (integer) (1 <= X <= 12)

    • card_holder — cardholder name.
      (string) (<= 255) (regex: ^[a-zA-Z - - ҐґЇїІіЄє0-9\s\-.']{1,255}$)

    • cvv— code for verifying the authenticity of the sender’s card.
      (string) (<= 3)

  • customer — information about the sender.

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

  • acs_info— information for 3-D Secure.

    • pa_req — encrypted payment data for 3-D Secure.
      (string) (<= 2048)

    • acs_url — Issuer URLs for 3-D Secure.
      (string<https-url>) (<= 4096)

    • md — merchant data in the payment system for 3-D Secure.
      (string) (<= 4096)

Fieldacs_infomay be empty (null), if the application is in a status other thanprocessing:awaiting_3ds_result.

3DS authentication confirmation

POST https://api.hh-processing.com/api/v1/payment/ecom/payin/confirm-3ds-result

Parameters that must be sent in the body of the request to confirm the debiting of funds from the user.

  • general — information about the application.

    • project_id — checkout ID received from HighHelp during the integration process.
      (string) (<= 32)

    • payment_id — payment identifier for which confirmation is performed.
      (string) (<= 255)

  • pares — information about the result of 3-D Secure.

    • data — data received from the issuer after authentication.
      (string) (<= 2^16)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/ecom/payin/confirm-3ds-result \
-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-ECOM-123456"
  },
  "pares": {
  	"data": "base64string"
  }
}'

Sample answer:

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

Response options:

  • status — payment processing status. The list of statuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • sub_status— payment processing substatus. Used only for individual statuses. The list of substatuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • status_description— additional information on status. Used if the payment did not go through or an error occurred.
    (string) (<= 1024)

  • request_id — payment identifier that is generated in the HighHelp system.
    (string) (<= 32)

  • project_id — checkout ID received from HighHelp during the integration process.
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s checkout.
    (string) (<= 255)

Payment statuses

Types of operations and statuses are described in sectionTransaction types and statuses.
Status codes and possible valuesstatusAndsub_statusare given in sectionStatus codes.

Status Substatus Description Payment status

error

The request was rejected due to an error related to the payment parameters.

Intermediate state

processing

new

The correctness of the request is checked before processing begins.

Intermediate state

requisites

Selection of details to which the client needs to transfer the amount from the request.

Intermediate state

awaiting_confirm

Confirmation of payment from the client is expected, since the details have already been provided.

Intermediate state

paid

The client confirmed that he sent the amount to the given details.

Intermediate state

dispute

no_payment

The client did not complete the payment for the application during its lifetime (lifetime).

Intermediate state

different_amount

The client sent an amount different from that specified in the application.

Intermediate state

confirm_timeout

The application expired, but the client later confirmed the payment and provided a receipt.

Intermediate state

decline

Payment declined

Final state

success

Payment completed

Final state

Alerts

It is recommended to implement checking of incoming notifications for duplicates. The idempotency key can be generated using a template{project_id}:{payment_id}:{status}:{sub_status}. Repeated notifications with the same key should be ignored to ensure that the same request is not processed twice.

Each alert is digitally signed by HighHelp. The current public key for verifying the signature can be obtained in the admin panel. The key is unique for each cash register. The signature verification algorithm is the reverse of the signature generation algorithm when calling an API. Examples of signature verification are given in sectionsAlert Signing (RSA)AndAlert signature (HMAC).

There are three types of alerts:

  • Informative— notifications in non-final statuses, if they are provided for a specific product (for example,processing:*, dispute:*orerror). The URL is specified in the parametermerchant_callback_urlwhen creating an application.

  • Successful— notifications for applications completed in statussuccess. The URL is specified in the parametermerchant_success_callback_url.

  • Unsuccessful— notifications for applications completed in statusdecline. The URL is specified in the parametermerchant_decline_callback_url.

The composition of the fields and the list of informative statuses depend on the product and integration scenario. See more details.H2H AlertsAndWidget Alerts.

Informative Alerts

Example of a notification with statusesprocessing:awaiting_3ds_resultAndprocessing:awaiting_redirect_result:

{ "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782", "general": { "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3", "payment_id": "KZT-ECOM-123456" }, "status": { "status": "processing", "sub_status": "awaiting_3ds_result", "status_description": null }, "payment_info": { "amount": 7000, "old_amount": 7000, "initial_amount": 3000, "currency": "KZT", "lifetime": 300, "expiration_date": 1721647251, "updated_date": 1721647251, "created_date": 1721647251, "method": "card-ecom", "type": "payin" }, "card": { "pan": "427212******1234", "year": 2029, "month": 1, "card_holder": "Alex Johnson" }, "customer": { "id": "cus_12345" }, // `processing:awaiting_3ds_result` "acs_info": { "pa_req": "123456789", "acs_url": "https://acs-url.com/order/1234", "md": "V2hhdCdzIHVwIGR1ZGU=" } // `processing:awaiting_redirect_result` "redirect_info": { "method": "POST", "url": "https://bank-domain.com/redirect/1234", "body": { "key1": "value1", "key2": "value2" } } }
  • Fieldacs_infomay be empty (null), if the application is in a status other thanprocessing:awaiting_3ds_result.

  • Fieldredirect_infomay be empty (null), if the application is in a status other thanprocessing:awaiting_redirect_result.

Successful Alerts

Alert sent on successful final statussuccess.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "427212***1234",
    "year": 2029,
    "month": 1,
    "card_holder": "Alex Johnson"
  },
  "customer": {
    "id": "cus_12345"
  }
}

Unsuccessful Alerts

Alert sent when final status is unsuccessfuldecline.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-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": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "427212***1234",
    "year": 2029,
    "month": 1,
    "card_holder": "Alex Johnson"
  },
  "customer": {
    "id": "cus_12345"
  }
}

Pay

Creating a payment request

POST https://api.hh-processing.com/api/v1/payment/ecom/payout

Parameters that must be sent in the body of the request when creating a payment to the card.

  • general — information about the application.

    • project_id — checkout ID received from 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— dynamic URL for receiving informative notifications (changes in intermediate application statuses, etc.). Notifications regarding the final status of applications are sent to the URLs specified inmerchant_success_callback_urlAndmerchant_decline_callback_url.
      (string<https-url>) (<= 2048)

    • merchant_success_callback_url— dynamic URL to receive a notification when the operation is successful.
      (string<https-url>) (<= 2048)

    • merchant_decline_callback_url— dynamic URL to receive an alert if the operation is not successful.
      (string<https-url>) (<= 2048)

  • receiver — details of the payment recipient.

    • pan — recipient’s card number.
      (string<pan>) (<= 32)

    • year— year of expiration of the recipient’s card. Required field for currencyUZS.
      (integer) (2020 <= X <= 2099)

    • month— month of expiration of the recipient’s card. Required field for currencyUZS.
      (integer) (1 <= X <= 12)

  • payment — information about payment.

    • method — payment method code. A list of methods is given in the sectionPayment methods.
      (string) (<= 32)

    • amount — payout amount in fractional currency units. For more details, see sectionCurrency codes.
      (integer) (1 <= X <= 10000000000000)

    • currency — payout currency in ISO-4217 alpha-3 format. For more information about currency codes, seeCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

    • description— payment description or comment. Displayed in the merchant's personal account.
      (string) (<= 255)

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

  • customer — information about the sender.

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

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

    • first_name— name of the client receiving the payment.
      (string) (<= 255)

    • last_name— surname of the client receiving the payment.
      (string) (<= 255)

    • country — user country code in ISO 3166-1 alpha-2 format.
      (string) (regex: ^[A-Z]{2}$)

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

    • browser— name and version of the user’s browser.
      (string) (<= 512)

    • device_type— user device type.
      (string) (<= 512)

    • user_agent— identification string of the client application.
      (string) (<= 1024)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/ecom/payout \
-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-ECOM-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/success",
    "merchant_decline_callback_url": "https://your-domain.com/decline"
  },
  "receiver": {
    "pan": "4242242442422424"
  },
  "payment": {
    "method": "card-ecom",
    "amount": 150000,
    "currency": "KZT",
    "description": "Comment about the payout",
    "extra_param": "example"
  },
  "customer": {
    "id": "cus_12345",
    "ip_address": "192.0.2.1",
    "first_name": "Alex",
    "last_name": "Johnson",
    "country": "RU",
    "email": "customer@example.com",
    "browser": "Google Chrome v15.12",
    "device_type": "iPhone 15 Pro",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
  }
}'

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-ECOM-123456"
}

Response options:

  • status — payment processing status. The list of statuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • sub_status— substatus of payment processing. Used only for individual statuses. The list of substatuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • status_description— additional information on status. Used if the payment did not go through or an error occurred.
    (string) (<= 1024)

  • request_id — payment identifier that is generated in the HighHelp system.
    (string) (<= 32)

  • project_id — checkout ID received from HighHelp during the integration process.
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s checkout.
    (string) (<= 255)

Fields marked, are mandatory.

Application information

POST https://api.hh-processing.com/api/v1/payment/ecom/payout/info

Parameters that must be sent in the body of the request to receive the statusecomapplications for payment.

  • general — information about the application.

    • project_id — checkout ID received from HighHelp during the integration process.
      (string) (<= 32)

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

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/ecom/payout/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-ECOM-123456"
  }
}'

Sample answer:

{
  "status": "processing",
  "sub_status": "payout_process",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "KZT-ECOM-123456",
  "payment_info": {
    "amount": 10000,
    "currency": "KZT",
    "method": "card-ecom",
    "type": "payout"
  }
}

Response options:

  • status — payment processing status. The list of statuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • sub_status— substatus of payment processing. Used only for individual statuses. The list of substatuses is given in the sectionPayment statuses.
    (string) (<= 32)

  • status_description— additional information on status. Used if the payment did not go through or an error occurred.
    (string) (<= 1024)

  • request_id — payment identifier that is generated in the HighHelp system.
    (string) (<= 32)

  • project_id — checkout ID received from HighHelp during the integration process.
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s checkout.
    (string) (<= 255)

  • payment_info — information about payment.

    • amount — the amount of the application in fractional currency units. For more details, see sectionCurrency codes.
      (integer) (1 <= X <= 10000000000000)

    • currency — code of the currency in which the payment is made, in the “ISO-4217 alpha-3” format. For more information about currency codes, seeCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

    • method — payment method code. A list of methods is given in the sectionPayment methods.
      (string) (<= 32)

    • type— payment type that was selected when creating the payment. For more information about types, seeSupported payment types.
      (string) (<= 32)

Payment statuses

Status Substatus Description Payment status

error

The request was rejected due to an error related to the payment parameters.

Intermediate state.

processing

new

Checking the request before processing.

Intermediate state.

requisites

Selection of a trader who will execute the payment.

Intermediate state.

payout_process

The payment process is carried out using the specified details.

Intermediate state.

dispute

incorrect_requisites

Incorrect payment details provided.

Intermediate state.

payout_failed

It was not possible to make a payment to the specified details.

Intermediate state.

payout_timeout

The payment was not executed before the application's lifetime expired.

Intermediate state.

decline

Operation diverted.

Final state.

success

The operation is completed.

Final state.

Alerts

It is recommended to implement checking of incoming notifications for duplicates. The idempotency key can be generated using a template{project_id}:{payment_id}:{status}:{sub_status}. Repeated notifications with the same key should be ignored to ensure that the same request is not processed twice.

Each alert is digitally signed by HighHelp. The current public key for verifying the signature can be obtained in the admin panel. The key is unique for each cash register. The signature verification algorithm is the reverse of the signature generation algorithm when calling an API. Examples of signature verification are given in sectionsAlert Signing (RSA)AndAlert signature (HMAC).

There are three types of alerts:

  • Informative— notifications in non-final statuses, if they are provided for a specific product (for example,processing:*, dispute:*orerror). The URL is specified in the parametermerchant_callback_urlwhen creating an application.

  • Successful— notifications for applications completed in statussuccess. The URL is specified in the parametermerchant_success_callback_url.

  • Unsuccessful— notifications for applications completed in statusdecline. The URL is specified in the parametermerchant_decline_callback_url.

The composition of the fields and the list of informative statuses depend on the product and integration scenario. See more details.H2H AlertsAndWidget Alerts.

Informative Alerts

Example of an alert with statusprocessing:payout_process:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "KZT",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payout"
  },
  "additional_info": {}
}

Successful Alerts

Alert sent on successful final statussuccess.

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

Unsuccessful Alerts

Alert sent when final status is unsuccessfuldecline.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-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",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payout"
  }
}