API integration (H2H)

This section provides an overview of H2H (host-to-host) integration for working with the HighHelp payment gateway API.

For more information about basic terms, seeBasic Concepts. The authentication and signature mechanism is described in sectionAuthentication and Signature.

What is H2H integration

API integration (H2H) is a scenario in which:

  • the user interacts only with the merchant interface;

  • The merchant's backend sends requests directly to the HighHelp API;

  • HighHelp processes the request and returns the result in a response and through alerts.

Unlike a widget (H2C):

  • the form of payment, collection of details and user scenarios are entirely implemented on the merchant’s side;

  • The merchant is independently responsible for protecting payment data on his side.

When to use H2H

H2H integration is used in the following cases:

  • Full control over UX and front-end logic (web, mobile applications) is required;

  • there is an existing payment form or payment module that needs to be connected to HighHelp;

  • it is necessary to flexibly manage order routing, logging and error handling on the merchant side;

  • use of the widget (H2C) is not possible due to technical or legal restrictions.

If your goal is to start accepting payments as quickly as possible, we recommend going through the scenario firstQuick start, and then return to H2H integration.

General interaction scheme

H2H integration uses the following components:

  • Merchant backend.

  • HighHelp payment gateway API (https://api.hh-processing.com).

  • External payment providers and banks are on HighHelp's side.

  • Merchant HTTP endpoints for receiving notifications (callbacks).

Basic flow for operationspayinAndpayout:

  1. The merchant backend generates the request body with blocksgeneral, paymentand additional blocks (sender, receiver, customeretc.).

  2. Authentication headers are generated (x-access-timestamp, x-access-merchant-id, x-access-token, x-access-signature).

  3. The request is sent to the HighHelp API using the H2H method (for example,/api/v1/payment/p2p/payinor/api/v1/payment/ecom/payin).

  4. HighHelp performs checks and returns a primary response with status (status, sub_status, request_id, payment_id).

  5. When the status of an application changes, HighHelp sends alerts to the URL specified in the fieldsmerchant_callback_url, merchant_success_callback_urlAndmerchant_decline_callback_url.

  6. If necessary, the merchant can obtain the current status of the application through a separate method…​/info(For example,…​/p2p/payin/info).

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

Payment Types and H2H Methods

Supported payment types are described in the sectionPayment types. Supported methods for H2H integration are listed in the sectionPayment methods (H2H).

Main groups of H2H scenarios:

  • P2P transfers (card-p2p, sbp-p2p, international-p2p, account-numberetc.).

  • Internet payments (ECOM) by card (card-ecom) — payment in one stage, see.One-step payment.

  • Additional operations and service endpoints described in sectionAPI service endpoints.

Type selection (payinorpayout) and method (payment.method) is determined by the business scenario and available geos.

Structure of requests and responses

General principles of query structure:

  • Blockgeneral— information about the application:

    • project_id— ticket office (project) identifier;

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

    • Alert URL (merchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url).

  • Blockpayment— payment parameters:

    • method— payment or payment method code;

    • amount— amount in fractional currency units;

    • currency— currency code in ISO 4217 alpha-3 format;

    • additional fields depending on the method.

  • Blockssender / receiver— details of the sender and recipient (card, account, etc.).

  • Blockcustomer— customer data (identifier, IP address, country, contact information, browser and device information).

Current field requirements for a specific method are given in the profile sections:

  • P2P H2H — separate files for specific countries, e.g.Russia.

  • ECOM H2H — One-step payment.

H2H API responses:

  • always contain aggregated status (status, sub_status, status_description);

  • contain identifiersrequest_id, project_id, payment_id;

  • may include additional blocks (payment_info, card, customer, acs_info, redirect_infoetc.) depending on the method and status.

For details on statuses and their descriptions, see the sectionStatus codes.

Authentication and Security

All H2H requests must be:

Recommended:

  • do not log private keys and header valuesx-access-signature;

  • store private keys in a secure secret vault;

  • check the signatures of all incoming notifications.

Alerts and idempotency

For all H2H scenarios, the following general principles for working with notifications apply:

  • HighHelp sends HTTP POST requests to the URLs specified inmerchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url.

  • Each alert contains:

    • project_idand blockgeneralwithpayment_idAndrequest_id;

    • blockstatuswithstatus, sub_status, status_description;

    • blockspayment_info, card, customeretc. depending on the status and type of operation.

  • The notification is signed with a HighHelp digital signature.

  • The notification is signed with a HighHelp digital signature.

Recommended:

  • check the notification signature using the same algorithm that is used when sending requests:

  • handle duplicate alerts using the idempotency key of the form{project_id}:{payment_id}:{status}:{sub_status};

  • if the notification endpoint is unavailable, use methods…​/infoto obtain the current status of the application.

Stages of implementing H2H integration

Recommended sequence of work:

  1. View the sectionsBefore you startAndBasic Concepts.

  2. Set up a test environment and access.

  3. Create a cash register, generate a key pair and set up signing requests for the sectionAuthentication and Signature.

  4. Implement H2H requests for the main scenario:

    • P2P payin— according to the manual for the selected geo (for example,Russia);

    • ECOM payin— by sectionOne-step payment.

  5. Implement notification processing and idempotency on the merchant backend side.

  6. Implement requests…​/infoto explicitly check application statuses.

  7. After testing is completed, agree on the transition to a productive environment.

For the first start and check of the working circuit, you can focus on the scriptQuick start.