H2H Alerts

This section describes alerts (callbacks) during API integration (H2H). Alerts are used to notify the merchant about changes in the status of the application: intermediate statuses, successful completion and errors.

Definitions of statuses and substatuses are given in sectionStatus codes. The mechanism for authenticating and signing requests and notifications is described in sectionsAlert Signing (RSA)AndAlert signature (HMAC).

Purpose of alerts

Alerts are used to transmit the result of processing an application from the HighHelp platform to the merchant's backend.

When working according to the H2H scheme:

  • The merchant's backend creates an application via API (for example, P2P or ECOM);

  • in the API response, the merchant receives the primary status (status, sub_status);

  • When the status changes further, HighHelp sends an HTTP request to predefined URLs.

Alerts are needed for:

  • tracking the progress of application processing;

  • recording the final result (success or failure);

  • obtaining additional data (amount, currency, masked details, authentication data, etc.).

Alert Types

H2H integration uses three types of alerts:

  • Informative Alerts— sent for non-final application statuses in the groupprocessing:*Anddispute:*. They are used for online display of processing progress and for logging, but should not trigger final business actions on the order (shipment, issuance of services, etc.).

  • Successful Alerts— sent once when the application reaches the final statesuccess. They contain the final parameters of the operation (amount, currency, method, identifiers) and confirm that the payment or disbursement was completed successfully and does not require additional processing attempts on the payment gateway side. They are used to fix payment or make a payment in the merchant’s system and subsequent business actions (order confirmation, balance change, etc.).

  • Unsuccessful Alerts— sent upon completion of the application in the final unsuccessful state (decline, including cases of expiration of the application lifetime). Contains the current valuestatus, sub_statusAndstatus_description, which can be used to determine the reason for the failure. They are used to record that the operation has not been completed, release reserved resources and prompt the user to repeat the payment or place a new request.

Alerts with statuserroralso sent tomerchant_callback_url.

Statuses, substatuses and their meanings are described in the sectionStatus codes.

Informative Alerts

Informative alerts are sent when an application enters intermediate statuses.

Examples of statuses:

  • processing:requisites;

  • processing:awaiting_confirm;

  • processing:awaiting_3ds_result;

  • processing:awaiting_redirect_result;

  • processing:paid;

  • processing:payout_process;

  • dispute:*;

  • error.

The URL for informative alerts is specified in the parametermerchant_callback_urlwhen creating an application.

Informative alerts are used to update the status on the merchant side (logging, displaying status to the user, launching internal processes).

Details (recipient_requisites) and payment instruction (additional_info) are included in the notification when payment details are available for the application (usually starting fromprocessing:awaiting_confirmand further in subsequent non-final statuses).
In other cases, these fields may have the valuenull, For example"recipient_requisites": null, "additional_info": null.

Successful Alerts

Successful alerts are sent when the application reaches final statussuccess. The URL for successful notifications is specified in the parametermerchant_success_callback_url.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-H2H-0001"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 10000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "427212******1234",
    "year": 2029,
    "month": 1,
    "card_holder": "Alex Johnson"
  },
  "customer": {
    "id": "cus_12345"
  }
}

These alerts are used for:

  • recording a successful write-off or payment;

  • performing the merchant’s business logic (changing order status, issuing a service, crediting bonuses, etc.).

Unsuccessful Alerts

Unsuccessful alerts are sent when the application reaches final statusdecline. The URL for unsuccessful notifications is specified in the parametermerchant_decline_callback_url.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-H2H-0001"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 10000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "427212******1234",
    "year": 2029,
    "month": 1,
    "card_holder": "Alex Johnson"
  },
  "customer": {
    "id": "cus_12345"
  }
}

Reasons for refusal are described in the fieldsstatusAndstatus_description. Status codes and meanings are given in the sectionStatus codes.

Alert Format

The alert is an HTTP requestPOSTin JSON format.

General parameters:

  • Method:POST.

  • Headlines:

  • Body: JSON object with application and status fields.

Below is an example of a successful transaction notificationpayin(structure may vary depending on product and method):

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "P2P-TEST-0001"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 10000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payin"
  }
}

Main fields:

  • project_id— identifier of the merchant’s cash register (project).

  • general— block with application identifiers.

    • request_id— application identifier in the HighHelp system.

    • payment_id— request identifier in the merchant system.

  • status— block with processing status.

    • status— main status (for example,processing, success, decline, error).

    • sub_status— substatus (maybenullfor some conditions).

    • status_description— additional text description of the status (usually filled in for errors and failures).

  • payment_info— block with payment parameters.

    • amount— the amount of the application in fractional currency units.

    • old_amount— the current amount of the application in fractional currency units.

    • initial_amount— the amount of the application at the time of creation in fractional currency units.

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

    • lifetime— request lifetime in seconds.

    • expiration_date— request expiration time in Unix Timestamp (UTC) format.

    • updated_date— time of the last change of the request in Unix Timestamp (UTC) format.

    • created_date— time of creation of the application in Unix Timestamp (UTC) format.

    • method— method of payment or disbursement.

    • type— payment type (payinorpayout).

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

Alerts with authentication data

For some ECOM H2H operations (for example, 3-D Secure), the alert may contain additional data to authenticate the client with the issuer.

Example for statusprocessing:awaiting_3ds_result:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_3ds_result",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 7000,
    "currency": "KZT",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  },
  "card": {
    "pan": "427212******1234",
    "year": 2029,
    "month": 1,
    "card_holder": "Alex Johnson"
  },
  "customer": {
    "id": "cus_12345"
  },
  "acs_info": {
    "pa_req": "123456789",
    "acs_url": "https://acs-url.com/order/1234",
    "md": "V2hhdCdzIHVwIGR1ZGU="
  }
}

Blockacs_infocontains data for generating an authentication form via 3-D Secure. A detailed example of 3-D Secure processing is given in the sectionOne-step payment.

Similarly, when using scripts with a redirect, a block can be usedredirect_infowith parameters:

  • method— HTTP method for the request.

  • url— address for client redirection.

  • body— request parameters (can be empty).

Alert signature verification

Each alert is digitally signed on the HighHelp side. Two signature algorithms are supported:

  • RSA-SHA256;

  • HMAC-SHA512.

To verify the signature, follow the steps:

  1. Get the key to verify the signature in the merchant’s personal account:

    1. Open sectionAPI → Callback settings.

    2. In the modal window below, check the line:Current algorithm: RSAorCurrent algorithm: HMAC.

    3. For RSA use blockPublic Keyand click on the download icon to save the key file.

    4. For HMAC use blockHMAC keyand store the secret HMAC key at the time of generation or update.

    5. With the current RSA algorithm, the window also displays the blockHMAC keyto generate an HMAC key.

  2. Configure the alert processing service to use the appropriate key:

    1. for RSA use the public key from the blockPublic Key;

    2. for HMAC use the secret HMAC key from the blockHMAC key.

  3. Implement the signature verification algorithm according to the selected signature algorithm:

Recommendations:

  • check the signature of all incoming alerts before processing business logic;

  • If there is a signature verification error, record the incident and do not perform operations on such an alert;

  • do not use unconfirmed data without verifying the signature to carry out transactions on the merchant’s side.

Idempotency and duplicate handling

Alerts may be resent if:

  • the previous request failed;

  • HighHelp did not receive a successful HTTP response from the merchant server;

  • The merchant server responded with a code different from the range2xx;

  • delivery was attempted again.

Recommended:

  • implement a check for duplicates;

  • use the view idempotency key{project_id}:{payment_id}:{status}:{sub_status};

  • ignore repeated notifications with a combination already processedstatusAndsub_status.

If the notification cannot be delivered (network error or unsuccessful response from the merchant server), the system repeats sending attempts until the request lifetime expires. It is important that alert processing is idempotent and does not require a long execution time.

Merchant's response to notification

Recommended notification response format:

  • HTTP status:200 OKupon successful processing.

  • Response body: empty or short confirmation (for example,{"status":"ok"}).

Recommended processing algorithm on the merchant backend side:

  1. Accept HTTP requestPOSTwith JSON body.

  2. Check the digital signature of the notification.

  3. Read idempotency key{project_id}:{payment_id}:{status}:{sub_status}.

  4. Check whether the given key has already been processed.

    • if processed, return a successful HTTP response and complete processing;

    • if not processed, execute business logic.

  5. Depending on the valuestatus:

    • forsuccessrecord successful completion;

    • fordeclinerecord the refusal;

    • fordispute:*record a controversial situation and process it according to business logic;

    • forprocessing:*update the intermediate state if necessary.

  6. Record the processing result in a log.

  7. Return HTTP response with code2xxin case of successful processing.

This behavior is the same for tickets created through the widget and through H2H.

Practical recommendations

Recommended:

  • Log all received alerts with key fields:

    • project_id, payment_id, request_id;

    • status, sub_status, status_description;

    • values ​​of amounts and currencies;

  • verify the signature before executing business logic;

  • implement idempotency by key{project_id}:{payment_id}:{status}:{sub_status};

  • process as final (success, decline), and intermediate (processing:*, dispute:*) status;

  • if necessary, obtain the current status of the application through methods…​/info(For example,p2p/payin/info, ecom/payin/info, ecom/payout/info). Request and response formats are described in specialized sections, such asOne-step paymentand P2P guidelines for relevant countries.