JavaScript integration example

An example of integration with the HighHelp payment gateway based on Node.js. H2H integration is demonstrated with request signing using the RSA-SHA256 algorithm, API calls to manage payments and disbursements, as well as alert processing.

The example also contains auxiliary modules for implementing signatures using the HMAC-SHA512 algorithm for requests and alerts.

The example is organized into separate scripts to perform API operations.

Requirements

  • Node.js version 18 and higher

  • npm version 9 and higher

The example has been tested on the specified versions. When using other versions, correct operation is not guaranteed.

Installation

Download example

  1. Download the archive with the example:js_example.zip.

  2. Unpack the archive.

  3. Open a terminal in the example directory.

Installing dependencies

Run the command:

npm install

Setting options

Open the fileconfig.jsand specify:

  • projectId— cashier ID (available in the merchant’s personal account:Box office → ID);

  • callbackUrl— URL for receiving alerts from HighHelp.

Setting up keys for signing requests

To sign API requests in the basic example scripts, an RSA private key is used using the RSA-SHA256 algorithm.

Follow the steps:

  1. Generate RSA keys in the merchant’s personal account, as described in sectionRequest Authentication and Signing (RSA).

  2. Save the private key to a fileprivate_key_for_api.pemin the root of the example directory.

The example contains a modulehelper_hmac.js, which implements request signing using the HMAC-SHA512 algorithm. If HMAC mode is enabled for your cash register, implement the signature according to the rules from the sectionRequest Authentication and Signing (HMAC)using this module. In HMAC mode the headerx-access-tokencontains the HMAC key mask.

Example composition

  • config.js— integration parameters (checkout ID, alert URL and base API URL);

  • helper.js— functions for generating request signatures using the RSA-SHA256 algorithm;

  • helper_hmac.js— functions for generating request signatures using the HMAC-SHA512 algorithm;

  • hmac_sign_callback.js— functions for checking the signature of alerts using the HMAC-SHA512 algorithm;

  • banks_get.js— receiving a list of banks;

  • payment_create.js— creating a payment request;

  • payment_get_info.js— obtaining payment status;

  • payout_create.js— creating an application for payment;

  • payout_get_info.js— obtaining payment status;

  • callback_processor.js— processing and validation of alerts.

Each script does:

  • generation of authentication headersx-access-*;

  • creating a request signature (using RSA-SHA256, if necessary - using HMAC-SHA512);

  • sending an HTTP request to the API;

  • processing the response and outputting the result.

Running Examples

Performing API operations

Run the required script. Examples:

node banks_get.js
node payment_create.js

The script sends a request to the API and displays the result in the terminal.

Execution result

If executed successfully, the script outputs:

  • generated request body;

  • server response.

If there is an error, information about the error returned by the API or signature generation logic is displayed.

Handling Alerts

Configuring keys for verifying notification signatures

To check the signature of notifications from HighHelp, the example uses:

  • public RSA key — when signing alerts using the RSA-SHA256 algorithm;

  • HMAC key — when signing alerts using the HMAC-SHA512 algorithm.

Follow the steps:

  1. Open your merchant's personal account.

  2. Go to sectionAPI → Callback settings.

    • In the modal window that opens, the following line is displayed at the bottom:Current algorithm: RSAorCurrent algorithm: HMAC.

    • With the current RSA algorithm, blocks are displayedPublic KeyHMAC key. To check the alert signature, usePublic Key.

    • With the current HMAC algorithm, a block is displayedHMAC key, blockPublic Keynot displayed.

  3. Save the key:

    • for RSA, click on the download icon in the blockPublic Keyand save the file to the root of the example directory;

    • for HMAC, store the secret HMAC key at the time of generation or update in the blockHMAC key.

  4. Make sure that the path and file name match the expected values ​​incallback_processor.js(change the settings in the script if necessary).

With the RSA algorithm configured in the blockHMAC keykey generation is available if it has not been generated previously. The secret HMAC key is available for download only at the time of generation or update. After downloading in the sectionAPI → Callback settingsthe masked key value is displayed; re-download is not available, only key update is available.

If you need to change the signature algorithm, contact your HighHelp manager.

A description of the alert signature format and verification algorithms is given in sectionsAlert Signing (RSA)Alert signature (HMAC).

Running the handler

Start the alert processing service:

node callback_processor.js

Service parameters:

  • port:8000;

  • endpoint: /callback/{status}.

The service accepts HTTP requests with alerts, validates the digital signature (RSA or HMAC depending on the configuration) and displays the verification result in the terminal.

If the signature is correct, the following message is displayed:

Signature is valid

Additional information