General requirements for P2P H2H

This section describes the integration of P2P payments using the H2H (host-to-host) scheme, when the merchant system directly calls the HighHelp API, and the user interface is completely implemented on the merchant side.

Definitions of basic terms (merchant, payer, recipient, P2P, cash desk) are given in the sectionGlossary. For general information about H2H integration, seeH2H Integration Overview.

Purpose P2P H2H

P2P H2H is used for transfers between individuals when:

  • the user initiates a transfer in the merchant interface.

  • The details of the sender and recipient are transmitted to the payment gateway via API.

  • Full control over the user interface and processing scripts is required.

  • It is permissible to work with payment details on the merchant’s side in accordance with security requirements.

Payment typespayinAndpayout, used in P2P scenarios, are described in sectionPayment types.

List of supported methods for P2P H2H (for example,card-p2p, sbp-p2p, international-p2p, account-number) is given in the sectionPayment methods (H2H).

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

Comparison of P2P H2H and P2P via widget

P2P can be implemented:

Differences:

  • At P2P H2H:

    • forms and scenarios for user interaction are developed on the merchant’s side.

    • card or account details go to the merchant's backend and are transmitted to HighHelp via API.

    • Responsibility for processing and storing details lies with the merchant.

  • For P2P via widget:

    • the payment form is rendered by the HighHelp widget.

    • payment details are sent directly to the payment gateway.

    • The merchant's backend receives information only about the application and its status.

P2P scenarios via widget are described in the sections:

Supported Scenarios

Within P2P H2H, the following scenarios are possible (the specific list depends on the cash register settings and connected providers):

  • P2P transfer by card (typepayin). The user transfers funds to the recipient's card. The payment method is selected fromPayment methods (H2H).

  • P2P transfer by phone number. Used for transfers through national fast payment systems, if available in the selected country.

  • P2P transfer to an account or other details. Used for local bank transfers in selected countries.

  • P2P payments (typepayout). If you have the appropriate settings, outgoing transfers in favor of clients or partners, for example, withdrawal of funds, are possible.

Supported countries and country codes are described in the sectionCountry codes. Supported currencies and rules for specifying amounts in fractional units are given in the sectionCurrency codes.

Geography and integration profiles

For P2P H2H, separate integration profiles are used by country. Each profile describes:

  • supported payment methods;

  • restrictions on amounts and currencies;

  • features of KYC and recipient verification;

  • additional fields and requirements for details.

Descriptions of profiles are found in the following sections:

It is recommended to start integration by reading the overview for the desired country, and then move on to implementing requests and processing responses.

General P2P H2H Processing Process

Below is a generalized process for processing a P2P payment using the H2H scheme.

The specific request and response fields vary by country and method.

  1. The merchant generates and sends a request to create an application.

    • The request specifies:

      • cash register IDproject_id.

      • payment IDpayment_id(unique within the merchant’s checkout).

      • payment parameters (amount, currency, method, payment type).

      • sender and recipient data.

      • Alert URLmerchant_callback_url, merchant_success_callback_url, merchant_decline_callback_url.

    • Authentication headersx-access-timestamp, x-access-merchant-id, x-access-token, x-access-signatureare formed according to the rules from the sectionAuthentication and Signature.

  2. HighHelp accepts the request and performs the initial check.

    • Checked:

      • correctness of the request structure and required fields.

      • availability of method and currency for the cash register.

      • restrictions on amounts and geography.

    • Upon successful verification, an application is created and a status is assigned, for exampleprocessing:new. Statuses and substatuses are described in the sectionStatus codes.

  3. The application is undergoing further processing.

    • Antifraud and compliance checks are performed.

    • Providers or traders are selected to execute the operation.

    • The status of the application may change (for example,processing:requisites, processing:payout_processetc.).

  4. HighHelp sends alerts when status changes.

    • Informative alerts are sent tomerchant_callback_url.

    • Successful alerts (statussuccess) are sent tomerchant_success_callback_url.

    • Unsuccessful alerts (statusdecline) are sent tomerchant_decline_callback_url.

    • The notification format is described in the sectionH2H Alerts.

  5. The merchant records the result and executes the business logic.

    • For final statusessuccessordeclinethe status of the order or transfer on the merchant side is updated.

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

    • If necessary, intermediate statuses are logged.

  6. If necessary, the merchant requests the status of the application via the API.

    • Methods are provided for P2P…​/payin/infoand, if available, methods for obtaining payment status.

    • The response includes the current valuesstatus, sub_status, as well as payment parameters. The format is described in the profile sections by country.

Integration requirements

When integrating P2P H2H, it is recommended to consider the following requirements:

  • Correct amount and currency.

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

    • The number of fractional digits for each currency is described inCurrency codes.

  • Correctness of country and geo indication.

    • The country code is specified in ISO 3166-1 alpha-2 format.

    • For a list of supported countries, seeCountry codes.

  • Using the correct methods.

  • Processing statuses and errors.

    • The processing logic must take into account the final and intermediate statuses fromStatus codes.

    • It is recommended to implement idempotency when processing alerts (for example, by key{project_id}:{payment_id}:{status}:{sub_status}).

  • Security and data storage.

    • It is necessary to ensure the protection of users' personal and payment data.

    • When working with card details, you must comply with the requirements of relevant standards and regulators.

Next steps

To implement P2P H2H integration, study: