Review of online payments via widget

This section describes the scenario for online payments (ECOM) through the HighHelp payment widget. The widget is used according to the H2C (host-to-client) scheme: the payment form is rendered on the HighHelp side, and on the merchant side, the widget is embedded and the results are processed.

For definitions of the main entities (merchant, payer, recipient, cash register, widget), see sectionGlossary. A general overview of the widget is given in the sectionWidget overview. A brief comparison of the H2H and H2C schemes is described in sectionReview of ECOM H2H.

When to use the widget for ECOM

Internet payments via widget are recommended to be used in the following cases:

  • You need to accept payments for goods and services in a web application or mobile web interface.

  • You need a payment form with ready-made logic for entering details, localization and error handling.

  • The merchant does not want to process and store payment details on his side.

  • It is required to reduce the amount of integration on the backend and focus on business logic.

The widget is suitable for scenarios:

  • one-step payment (funds are written off when creating an application);

  • subsequent processing of the result based on alerts and through API requests.

A payment script is available for the ECOM widget (payin). General payment types are described in the sectionPayment types. Supported methods for the widget are given in the sectionWidget Methods.

Architecture and roles

The scenario for online payments via widget involves:

  • Payer browser.

  • Merchant frontend (the page into which the widget is embedded).

  • Merchant backend.

  • HighHelp payment gateway (widget and API).

General approach:

  • The merchant backend creates a request via the HighHelp API and receives parameters for initializing the widget.

  • The merchant's frontend embeds a widget (for example, through a JavaScript widget and a container foriframe).

  • The payer enters data on the payment page (HighHelp widget).

  • HighHelp processes the payment and, if necessary, performs 3-D Secure or other authentication scripts.

  • HighHelp sends alerts to the merchant's backend and returns the result to the payer's interface.

Authentication of requests from the merchant backend to the HighHelp API is described in the sectionAuthentication and Signature.

Processing of online payment via widget

Below is a simplified process for processing online payment through the widget. Specific fields and statuses depend on the method and checkout settings.

  1. The merchant's backend creates an application via the API.

  2. The backend receives data from the API to initialize the widget.

    • The response may return a session ID, token, or configuration parameters for the frontend.

    • These values ​​are sent to the frontend (for example, via a JSON response from the merchant backend).

  3. The frontend initializes the widget.

    • The HighHelp script is connected to the merchant's page.

    • In the frontend code, the widget initialization function is called with parameters received from the backend.

    • The widget displays the payment form for the payer.

  4. The payer fills in payment information.

    • Enters card details or selects another payment method.

    • If necessary, it undergoes additional authentication (for example, 3-D Secure).

  5. HighHelp processes the payment.

    • Performs checks and interacts with payment providers.

    • Generates the final result (successordecline) and informative statuses (processing:*, error).

  6. HighHelp sends alerts to the merchant's backend.

    • Informative alerts are sent tomerchant_callback_url.

    • Successful alerts are sent tomerchant_success_callback_url.

    • Unsuccessful alerts are sent tomerchant_decline_callback_url.

    • The notification format is described in the sectionWidget Alerts.

  7. The merchant's backend records the result of the operation.

    • Updates the status of an order or service.

    • Responds to the frontend (e.g. via API or websockets) to display the result to the user.

If necessary, the merchant can request the status of the application via the API…​/info. The format of such requests and responses is described in the profile sections for the products.

Online payment processing scheme via widget

flowchart TD U[ ] M[ ] W[ HighHelp] S[ ] D[ ] C{ 3-D Secure?} B1[ ] B2[ ] B3[ ] H[ API HighHelp] RS{ } OK[ ] FAIL[ ] U --> M M --> W W --> S S --> D D --> C C -- --> H C -- --> B1 B1 --> B2 B2 --> B3 B3 --> H H --> RS RS -->|success| OK RS -->|decline| FAIL

Application format

The composition and format of the fields depend on the specific widget method and geography. A typical scenario uses the following blocks:

  • general— general information about the application.

    • project_id— cashier identifier.

    • payment_id— payment ID in the merchant’s system.

    • merchant_callback_url— URL for informative alerts.

    • merchant_success_callback_url— URL for successful alerts.

    • merchant_decline_callback_url— URL for unsuccessful alerts.

  • payment— payment parameters.

    • widget_method— payment page method code. A list of values ​​is given in the sectionWidget Methods.

    • amount— amount in fractional currency units.

    • currency— currency code in ISO 4217 alpha-3 format. See sectionCurrency codes.

  • customer— information about the payer.

    • id— user ID in the merchant system.

    • additional fields (country, language, contact information) depend on the specific cash register settings and geography.

A detailed list of fields and restrictions (type, length, mandatory) are described in the profile sections:

Handling statuses and errors

When working with online payments through a widget, you must:

  • process final statusessuccess, decline;

  • process informative statuses (processing:*) for logging and diagnostics;

  • take into account intermediate statuses (processing:*), especially in scenarios with 3-D Secure and redirects;

  • use fieldstatus_descriptionto diagnose errors and causes of failure.

The list of statuses and substatuses is given in the sectionStatus codes.

Recommended:

  • implement the logic for idempotent notification processing on the backend;

  • log all incoming alerts and key fields (project_id, payment_id, status, sub_status);

  • use methods if necessary…​/infoto explicitly check status.

Frontend requirements

When integrating a widget on the frontend, you should consider:

  • The page must load over HTTPS.

  • It should be possible to execute JavaScript code and insert a container for the widget.

  • Needs to be processed:

    • successful completion of payment;

    • failure or error;

    • event of closing the widget by the user (if provided).

Recommended:

  • use separate frontend routes for the page with the widget and for the result page;

  • do not block the main JavaScript execution thread with long operations when initializing the widget;

  • provide for handling situations when the widget cannot be loaded (network error, script blocking).

Next steps

To fully integrate online payments via widget: