Basic Concepts

This section contains basic terms and entities that are used in the documentation of the HighHelp payment gateway. The section is aimed at developers who set up integration via API (H2H) and/or through the HighHelp payment widget.

For formal definitions of terms, you can useGlossary.

Participants and Core Entities

Payment gateway HighHelp

A payment service that accepts requests from merchant systems, processes payments and transfers, interacts with banks and external providers, and returns the result.

Merchant

A company or service that integrates with HighHelp via API and/or through the HighHelp payment widget to accept payments or make transfers.

Payer

The end user (merchant's client) who initiates the payment or transfer.

Recipient

The user to whose details funds are actually credited. In P2P scenarios, the recipient is the recipient of the transfer.

(project / merchant cashbox)

Merchant's internal settlement account in the payment gateway. The cash register has an IDproject_id. Credits, write-offs and payments are processed through the cash register.

Cash balance

Current cash balance by currency. Available balance fields are described in the sectionCash balance.

Frozen Balance

Part of the cash balance reserved for unfinished transactions, for example, until payment is completed or the debit is confirmed.

Project

Logical unit of merchant integration (online store, service, application), linked to the cash register. Payment methods and notification URLs are configured for the project (merchant_*_callback_url) and routing parameters.

Payment, transaction and payment types

Payment

Business scenario for moving funds, for example, payment for an order or P2P transfer. Identified by fieldpayment_idwithin a specific cash register.

Operation

Technical unit of processing within a payment gateway (debit, credit, return, payout, etc.). One payment may include one or more transactions.

Payment types

The following types are used in the documentation:

  • payin— incoming payment from the user in favor of the merchant.

  • payout— outgoing payment from the merchant in favor of the user.

The list of payment types is described in the sectionPayment types.

Products: P2P and ECOM

The system supports several product scenarios.

P2P

Transfer scenarios between users, for example, transfer from card to card. For such operations, methods of the form are usedcard-p2p, sbp-p2petc. The list of H2H integration methods is given in the sectionPayment methods (H2H).

ECOM

Scenarios for online payments for goods and services (e-commerce). For ECOM H2H payments and payouts with method are availablecard-ecom. For ECOM via widget (H2C) payment methods are availablepayin-ecom-cardAndpayin-ecom-mobile. An example of an H2H scenario is given in the sectionOne-step payment.

Supported methods for the payment page are listed in the sectionWidget Methods.

Integration options: H2H and widget

Integration with HighHelp is possible in two scenarios.

API integration (H2H, host-to-host)

The merchant backend directly calls the payment gateway API. The payment form and user interface are implemented on the merchant side. The merchant transmits payment instrument details and client data in the body of the request, receives statuses and processes alerts.

Integration via the HighHelp payment widget

The payment form is placed on the HighHelp side (HighHelp payment widget) and integrated into the merchant’s website or application, for example, viaiframeor JavaScript widget. The payer enters payment information on the payment page of the widget. The payment gateway accepts and processes the data, and the merchant receives the result via API and alerts.

The list of methods that are used to pre-select payment scenarios on the payment page is given in the sectionWidget Methods.

Structure of requests and responses

A typical request to the HighHelp API uses several logical blocks.

general

Mandatory block with general information on the application. Typically contains:

  • project_id— cashier identifier.

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

  • dynamic URLs for alerts (merchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url) for a specific application.

payment

Block with payment parameters:

  • method— payment or payout method code for H2H integration. A list of methods is given inPayment methods (H2H).

  • widget_method— payment page method code for H2C integration via widget. A list of methods is given inWidget Methods.

  • amount— transaction amount in fractional currency units.

  • currency— currency code in ISO 4217 alpha-3 format. The list of currencies is given inCurrency codes.

sender / receiver

Blocks with sender and recipient details in P2P and payout scenarios. Depending on the method, they may contain the card number, account number and additional attributes.

card

A block with card details explicitly, if they are transmitted via H2H integration. Contains card number, expiration date, holder name and CVV.

customer

Block with information about the merchant's client:

  • id— client identifier in the merchant system.

  • ip_address— Client IP address.

  • country— country code in ISO 3166-1 alpha-2 format. A list of countries is given inCountry codes.

  • additional attributes (interface language, browser, user agent, etc.).

API responses contain:

  • technical fields (request_id, project_id, payment_id);

  • fields with status (status, sub_status, status_description);

  • blockspayment_info, card, customerand additional data for authentication or redirection.

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

Identifier and status

The following key identifiers are used in requests and alerts.

project_id

Identifier of the merchant's checkout in the HighHelp system. Sent in every request and notification.

payment_id

Payment ID in the merchant system. Must be unique within one cash register. The merchant uses it to connect requests, responses and notifications.

request_id

Application ID in the HighHelp system. Generated when a request is created and returned in responses and notifications.

To describe the payment status the following are used:

status

Basic processing status, e.g.processing, success, decline, error.

sub_status

A substatus that specifies a state within the main status, e.g.new, awaiting_3ds_result, payout_process.

status_description

Text description of the reason for the refusal or special condition, for example, anti-fraud error codes.

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

Alerts

To inform the merchant about changes in the status of the application, HTTP notifications are used to the addresses specified in the blockgeneral:

  • merchant_callback_url— informative alerts on intermediate statuses.

  • merchant_success_callback_url— notifications about successful completion.

  • merchant_decline_callback_url— notifications about unsuccessful completion.

Alerts contain the same identifiers (project_id, payment_id, request_id) and status fields (status, sub_status, status_description) as API responses.

Each notification is signed with a digital signature generated using the same algorithm as the signature of API requests. The procedure for generating a signature is described in the sectionAuthentication and Signature.

It is recommended to implement protection against repeated processing of duplicate alerts using an idempotency key of the formproject_id:payment_id:status:sub_status.

Help Topics