Review of ECOM H2H

This section describes the integration of Internet payments using bank cards in the H2H (host-to-host) format. With this integration option, the payment form and collection of details are performed on the merchant’s side, and the payment is created and processed through the HighHelp API.

Purpose of ECOM H2H

ECOM H2H is used for online payments by bank cards when:

  • the payment form is posted on the merchant’s website or application;

  • card details are sent to the merchant’s backend and transferred to the payment gateway via API;

  • requires full control over the user interface and error handling;

  • It is acceptable to work with card data on the merchant side (PCI DSS requirements).

For ECOM H2H payment types applypayinAndpayout. Definitions of payment types are given in the sectionPayment types. List of supported payment methods for H2H (includingcard-ecom) is given in the sectionPayment methods (H2H).

All ECOM H2H requests use the authentication and signature mechanism described in sectionAuthentication and Signature.

Comparison with widget (H2C)

ECOM H2H differs from widget integration (H2C) in the following ways:

  • At H2H:

    • the form of payment and entering details are implemented on the merchant’s side;

    • the merchant accepts and processes card data;

    • requests to the payment gateway are made from the merchant's backend.

  • At H2C:

    • the payment form is rendered by the HighHelp widget;

    • The card details are sent directly to the payment gateway;

    • The merchant's backend receives only the processing result.

Integration via widget is described in the sectionInternet payments via widget.

Supported Scenarios

The following basic scenarios are supported within ECOM H2H:

  • Payment by card (typepayin). The client enters card details on the merchant’s side, the merchant creates an applicationcard-ecomand receives the processing result. Funds are debited from the client's card and credited to the merchant's cash register.

  • Payment to card (typepayout). Merchant creates an ordercard-ecomfor payment. Funds are debited from the merchant's cash register and credited to the recipient's card.

Supported currencies and features of specifying amounts in fractional units are described in the sectionCurrency codes.

The list of application statuses and substatuses, as well as the corresponding error codes, is given in the sectionStatus codes.

General processing process of ECOM H2H

The general ECOM H2H payment processing process includes the following steps:

  1. Formation of a request on the merchant side.

    1. The merchant collects client data and card details.

    2. On the backend, the body of the request to the HighHelp API with blocks is generatedgeneral, payment, cardAndcustomer(for payin) orreceiverAndpayment(for payout).

    3. Authentication headers are generatedx-access-timestamp, x-access-merchant-id, x-access-token, x-access-signatureaccording to the rules fromAuthentication and Signature.

  2. Sending an HTTP request to the HighHelp API.

    1. Endpoint is used for ECOM payinpayment/ecom/payin.

    2. Endpoint is used for ECOM payoutpayment/ecom/payout.

  3. Initial processing of the application.

    1. The system checks the correctness of the request and the availability of the operation for the cash register.

    2. The application is assigned a statusprocessing:newor error. For a description of statuses, see sectionStatus codes.

  4. Additional authentication (3-D Secure or redirect) if necessary.

    1. The issuer may require 3-D Secure or other form of customer authentication.

    2. In this case, the application goes into one of the intermediate statuses (processing:awaiting_3ds_resultorprocessing:awaiting_redirect_result).

    3. Authentication data is sent to the merchant in the body of the notification. The procedure for working with 3-D Secure is described in the sectionOne-step payment.

  5. Completion of the application.

    1. After all checks have been completed, the application moves to one of the final statuses:

      • success— the operation was completed successfully.

      • decline— operation diverted.

      • error— the request was rejected due to an error related to the payment parameters.

    2. Information about the result is transmitted to the merchant in the form of an alert.

  6. Request application status via API if necessary.

    1. The merchant can request the current status of the application through the methods…​/payin/infoAnd…​/payout/info.

    2. The response format and set of fields coincide with the data that comes in notifications.

Integration requirements

When integrating ECOM H2H you should consider:

  • Processing card data.

    • The card details pass through the merchant's infrastructure.

    • It is required to ensure compliance with security requirements (for example, PCI DSS) on the merchant side.

  • Correctness of amounts and currencies.

    • The amount is transferred in fractional currency units without separators.

    • Information on the number of fractional digits is given in the sectionCurrency codes.

  • Using correct payment methods.

  • Processing statuses and alerts.

    • It is necessary to process the final and intermediate statuses described inStatus codes.

    • It is recommended to implement protection against repeated processing of duplicate notifications (the idempotency key can be constructed, for example, as{project_id}:{payment_id}:{status}:{sub_status}).

Next steps

  • One-step payment— description of order creationcard-ecomfor payment and disbursement, examples of requests and responses, working with 3-D Secure and alerts.

  • Authentication and Signature— rules for forming authentication headers and digital signatures.

  • Payment types— assignment of typespayinAndpayout.

  • Payment methods (H2H)— list of supported methods and reference to geographies.

  • Currency codes— supported currencies and number of fractional digits.

  • Status codes— statuses and substatuses of applications, error codes and their purpose.