Review of integration examples

This section describes examples of integration with the HighHelp payment gateway. The examples are intended to speed up the implementation of H2H integration and demonstrate the basic cycle of working with the API:

  • generation of authentication headers and digital signatures;

  • sending requests to the API;

  • processing responses and errors.

Headingx-access-tokenhas a different meaning: with RSA it contains the public key in Base64Url, with HMAC it contains the mask of the secret HMAC key.

In the current version, the examples use request signing using the RSA-SHA256 algorithm. The examples also contain auxiliary modules for working with HMAC (generating request signatures and checking alert signatures).

Rules for authentication and signature generation:

The general scenario for the first payment is described in the sectionQuick start.

Composition of examples

The following examples are available in the current version:

Each example:

  • uses a unified approach to generating request signatures (RSA-SHA256);

  • contains minimal working code to perform payment and check status;

  • shows the basic structure of the project and working with the configuration;

  • includes support functions for data normalization and signature generation (RSA and HMAC) that can be used in your own integration.

A specific set of endpoints and scenarios (creating a payment, obtaining information about an application, etc.) is described in the documentation for each example.

What do the examples illustrate?

The examples illustrate a typical H2H scenario with RSA authentication:

  • loading configuration (checkout ID, private RSA key, base API URL, alert settings);

  • generating the body of a request to create a payment;

  • normalization of data and generation of a message for signature;

  • creating a digital signature and setting headersx-access-*;

  • sending an HTTP request to the API;

  • response parsing and basic error handling;

  • checking the digital signature of notifications.

For integrations using HMAC, follow the general steps in the examples and the rules in sectionRequest Authentication and Signing (HMAC), as well as sectionAlert signature (HMAC). The examples contain helper functions for HMAC.

Environment requirements

Before using the examples, make sure that:

  • you have access to the merchant’s account and a cash register has been created;

  • the cash register is configured and API keys are generated for it in the merchant’s account;

  • the current cash register signature algorithm is known: RSA-SHA256 or HMAC-SHA512;

  • for HMAC integration, switching of the signature algorithm has been agreed upon and the secret HMAC key has been saved;

  • you can make requests tohttps://api.hh-processing.comfrom your environment;

  • The required versions of the interpreter/engine for the selected example (PHP or Node.js) are installed.

Gaining access to your account, creating a cash register and authentication parameters are described in the sections:

The technical requirements and run commands for each example are listed in:

Recommendations for use

Recommended:

  • first set up a test environment and run the basic script from sectionQuick start;

  • then deploy and run the example in the selected language;

  • adapt the example to your infrastructure:

    • put secrets (cash ID, keys) into environment variables or a separate configuration file;

    • improve error handling and logging;

    • implement your own logic for storing and processing payment statuses.

The examples are not intended to be used without modification in a production environment. Use them as a minimum working basis for further development.