PHP integration example

An example of integration with the HighHelp payment gateway based on PHP. 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 additionally contains modules for implementing signatures of requests and alerts using the HMAC-SHA512 algorithm.

The example consists of independent scripts to perform API operations.

Requirements

  • PHP version 8.4.1 and higher

  • Composer version 2.8.3 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:php_example.zip.

  2. Unpack the archive.

  3. Open a terminal in the example directory.

Installing dependencies

Run the command:

composer install

Setting options

Open the fileconfig.phpand specify:

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

  • callback_url— URL for notifications of your service.

Setting up keys for signing requests

In the basic example scripts, requests to the API are signed with a private RSA key 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 the filehelper_hmac.php, which implements request signing using the HMAC-SHA512 algorithm. If HMAC mode is enabled for your cash register, use this module and follow the rules from the sectionRequest Authentication and Signing (HMAC). In HMAC mode the headerx-access-tokencontains the HMAC key mask.

Example composition

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

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

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

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

  • banks_get.php— receiving a list of banks;

  • payment_create.php— creating a payment request;

  • payment_get_info.php— obtaining payment status;

  • payout_create.php— creating an application for payment;

  • payout_get_info.php— obtaining payment status;

  • callback_processor.php— alert handler.

Each script contains:

  • generation of authentication headersx-access-*;

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

  • sending an HTTP request;

  • response processing.

Running Examples

Performing API operations

Run the required script. Examples:

php banks_get.php
php payment_create.php

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

Execution result

If executed successfully, the script outputs:

  • 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 the payment gateway, use:

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

Algorithms for generating and checking notification signatures are described in sectionsAlert Signing (RSA)Alert signature (HMAC).

Running the handler

Start the alert processing service:

php -S localhost:8000 callback_processor.php

Service parameters:

  • port:8000;

  • endpoint: /callback/{status}.

The service checks the signature of each incoming notification (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 (via OpenSSL)

Additional information