Order of widget integration

This section describes the standard procedure for integrating the HighHelp (H2C) payment widget on the merchant side.

General information about the widget and its purpose is given in the sectionWidget overview. Online payments via widget are described in the sectionInternet payments via widget. Authentication of API requests is described in sectionAuthentication and Signature.

Brief integration procedure

A typical widget integration includes the following steps:

  1. Set up access and test environment.

  2. Select widget usage scenarios and supported methods.

  3. Implement the creation of requests for the widget on the backend.

  4. Implement notification processing from HighHelp.

  5. Embed the widget into the frontend (merchant pages).

  6. Test the scripts in a test environment.

  7. Transfer integration to a productive environment.

The following sections describe each step in more detail.

Step 1. Prepare access and environment

Before integrating the widget, you must:

  • gain access to the merchant’s account and create a cash register;

  • generate API keys for the cash register and determine the signature algorithm (RSA-SHA256 or HMAC-SHA512);

  • set up a test environment;

  • make sure that the merchant's backend can send HTTPS requests to the HighHelp API.

It is recommended to follow the instructions from the sections sequentially:

To make the first test payment, you can use the sectionQuick start.

Step 2: Select Scenarios and Methods

At this step, it is determined which scenarios will be implemented through the widget:

  • Internet payments for goods and services (ECOM).

  • P2P transfers via widget (subject to the availability of relevant products and geographies).

  • Additional scenarios, if supported by the cash register settings.

Recommended:

  • see the supported methods of the payment page in the sectionWidget Methods;

  • check the codes of currencies and countries that you plan to use:

  • clarify which methods and geographies are available for your cash register in the merchant’s account.

Online payments via widget are described in the sectionInternet payments via widget. Additional requirements may be specified in product sections, for example, for P2P via a widget for individual countries.

Step 3. Implementation of creating requests on the backend

The merchant's backend is responsible for creating payment requests that are processed through the widget.

General approach:

  1. The backend receives a request from the frontend (for example, from the checkout page).

  2. The backend generates a request to the HighHelp API on behalf of the cash register.

  3. HighHelp creates a ticket and returns the data needed to initialize the widget or track status.

  4. The backend returns identifiers and parameters to the frontend that will be used when launching the widget.

Basic requirements:

  • All requests to the HighHelp API must be authenticated according to sectionAuthentication and Signature.

  • In the blockgeneralmust be indicatedproject_idpayment_id.

  • In the blockpaymentindicate the amount, currency and method of the payment page (widget_method) supported by the widget.

  • To correctly process notifications, specifymerchant_callback_url, merchant_success_callback_urlmerchant_decline_callback_url.

The detailed request format for online payments via the widget is given in the sectionInternet payments via widget.

Step 4. Processing alerts on the backend

HighHelp sends HTTP alerts when the status of an application changes. The merchant's backend must be able to:

  • accept HTTP requestsPOSTwith JSON body;

  • check the digital signature of notifications;

  • handle repeated alerts;

  • update the order status in your own system.

Recommended:

  • provide separate URLs for:

    • informative alerts (merchant_callback_url), if they are used in the selected scenario;

    • successful notifications (merchant_success_callback_url);

    • unsuccessful alerts (merchant_decline_callback_url);

  • use the view idempotency key{project_id}:{payment_id}:{status}:{sub_status}to protect against re-processing;

  • Log all incoming alerts.

The alert structure and JSON examples are described in sectionWidget Alerts. General principles for processing alerts and statuses are also discussed in sectionAlerts (H2H). Status and substatus codes are given in the sectionStatus codes.

Step 5. Embedding the widget in the frontend

The merchant's frontend is responsible for displaying the payment form (widget) to the payer.

Typical scheme:

  1. The frontend page sends a request to the backend to create a request.

  2. The backend creates a request in the HighHelp API and returns identifiers and parameters to the frontend to initialize the widget.

  3. The frontend loads the widget script (according to the instructions from the dashboard or from the example).

  4. The frontend calls the widget initialization function, passing parameters (application ID, token or other data).

  5. The widget displays the payment form and controls the entry of details.

  6. Upon completion of the operation, the widget displays the result to the payer (success, refusal, error), and the backend receives an alert.

Recommended:

  • place the widget on a page accessible via HTTPS;

  • provide a container for the widget (for example, a separate block with a fixed width);

  • display loading status if the widget is initialized asynchronously;

  • handle the scenario when the widget cannot be loaded (network error, script blocking, etc.).

A specific example of JavaScript code for connecting and initializing a widget is available inexamples of integration.

Step 6. Testing in a test environment

After implementing the backend and frontend, you need to test the integration in a test environment.

Recommended:

  • use test URLs and details;

  • check the following scenarios:

    • successful payment via widget;

    • refusal at the initiative of the client;

    • refusal due to an error or anti-fraud (if test scripts are provided);

    • correct processing of informative alerts;

    • correct processing of successful and unsuccessful notifications;

  • compare statuses and substatuses from responses and notifications with descriptions in the sectionStatus codes.

If necessary, you can use methods…​/infoto explicitly check the status of the application described in the profile sections for the products.

Step 7. Transferring the integration to a production environment

After successful testing:

  • switch the base API and widget URLs to the production environment;

  • use keys and cash register designed for a productive environment;

  • make sure alerts are sent to productive URLsmerchant_callback_url, merchant_success_callback_urlmerchant_decline_callback_url;

  • enable error monitoring and logging of API requests and alerts in the system.

Additionally recommended:

  • set up alerts for key errors and failures;

  • document the internal status processing processsuccessdeclinefor the development and support team.

Next steps

To deepen integration and customize individual scenarios: