Widget Alerts

This section describes the HTTP callbacks that HighHelp sends when the status of requests created through the payment widget (H2C) changes. An overview of how the widget works is given in the sectionWidget overview.

Definitions of statuses and substatuses are given in sectionStatus codes. The authentication and signature mechanism is described in sectionAuthentication and Signature.

Purpose of alerts

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

Alerts are needed for:

  • tracking the progress of application processing;

  • recording the final result (success or failure);

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

Basic alert structure (fieldsproject_id, general, status) is the same for H2H and widget, but the composition of additional blocks depends on the product and integration scenario. A complete list of statuses and substatuses is given in the sectionStatus codes.

Alert Types

For orders created through the widget, three types of alerts are used:

  • Informative Alerts— sent when the intermediate statuses of an application change, if they are provided for the selected scenario. The URL for informative alerts is indicated in the fieldmerchant_callback_urlwhen creating an application.

  • Successful Alerts— sent when the application is transferred to final statussuccess. The URL is indicated in the fieldmerchant_success_callback_url.

  • Unsuccessful Alerts— sent when the application is transferred to final statusdecline. The URL is indicated in the fieldmerchant_decline_callback_url.

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

Transport and format

HighHelp sends alerts:

  • methodPOST;

  • in JSON format;

  • with UTF-8 encoding;

  • with titleContent-Type: application/json.

Each alert contains:

  • cash register and payment information;

  • current status and substatus;

  • information about the amount, currency and method;

  • additional blocks specific to the product, for example, information about the card or client.

Examples of JSON structures are given below.

Informative Alerts

For statusprocessingthe set of informative alerts depends on the payment scenario and is described in the relevant sections.

An example of an informative notification for a P2P payment via a widget:

{ "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782", "general": { "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3", "payment_id": "P2P-WIDGET-0001" }, "status": { "status": "processing", "sub_status": "awaiting_confirm", "status_description": null }, "payment_info": { "amount": 7000, "old_amount": 7000, "initial_amount": 7000, "currency": "RUB", "lifetime": 300, "expiration_date": 1721647251, "updated_date": 1721647251, "created_date": 1721647251, "method": "card-p2p", "widget_method": "payin-p2p-card", "type": "payin" }, "recipient_requisites": { "pan_hidden": "2202****6980", "card_holder_hidden": " **** ", "bank_name": "t-bank", "bank_country": "RU", "currency": "RUB" }, "integration": { "form_url": "https://pay.****host.com/****6789", "redirect_url": "https://your-domain.com/order/page" } }

Masked details in the blockrecipient_requisitestransmitted only for statusesprocessing:awaiting_confirmprocessing:paid. For other substatusesprocessing:*blockrecipient_requisitesnot transmitted. In notifications with statusessuccess, decline, errordispute:*blockrecipient_requisitesalso not transmitted.

The merchant can use informative alerts to update the order status on his side.

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-WIDGET-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",
    "widget_method": "payin-ecom-card",
    "type": "payin"
  }
}

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.).

If you receive such an alert, we recommend that you:

  • record the successful completion of the transaction in the merchant’s system;

  • update order status;

  • do not re-write off or re-process an already processed application.

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-WIDGET-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",
    "widget_method": "payin-ecom-card",
    "type": "payin"
  }
}

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

Alert Format

The notification is an HTTP POST request in JSON format.

General parameters:

  • Method:POST.

  • Headlines:

  • Body: JSON object with application and status fields.

General alert structure:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "WIDGET-PAYIN-0001"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 10000,
    "currency": "USD",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "type": "payin"
  },
  "recipient_requisites": {
    "pan_hidden": "4850****1726",
    "card_holder_hidden": "Al****on",
    "bank_name": null,
    "bank_country": null,
    "currency": "USD"
  },
  "integration": {
    "form_url": "https://pay.****host.com/****6789",
    "redirect_url": "https://your-domain.com/order/page"
  }
}

Main fields:

  • project_id— cashier identifier in the HighHelp system.

  • general— general information about the application.

    • request_id— application identifier in the HighHelp system.

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

  • status— application processing status.

    • status— main status of the application. Values ​​are described inStatus codes.

    • sub_status— substatus of the application. Values ​​are described inStatus codes.

    • status_description— text description of the status, used in case of errors or failures.

  • payment_info— payment parameters.

    • amount— amount in fractional currency units.

    • old_amount— previous amount in fractional currency units.

    • initial_amount— initial amount in fractional currency units.

    • currency— currency code in ISO 4217 alpha-3 format. The options are described inCurrency codes.

    • lifetime— request lifetime in seconds.

    • expiration_date— the expiration date of the application.

    • created_date— date of creation of the application (timestamp).

    • updated_date— date of application update (timestamp).

    • method— basic payment processing method (for example,card-ecom). Values ​​are described inPayment methods (H2H).

    • widget_method— (if present) payment page method. Values ​​are described inWidget Methods.

    • type— payment type (payinorpayout). Values ​​are described inPayment types.

  • recipient_requisites— disguised recipient details (if available).

  • integration— links for integration (for example,form_url, redirect_url).

The specific composition of the fields may vary depending on the product and method (P2P, ECOM, payout).

A complete list of possible statuses and substatuses is given inStatus codes.

Authentication data (3-D Secure)

For applications created through the payment widget, data for passing 3-D Secure and other types of authentication is processed inside the HighHelp widget. In HTTP notifications to the merchant systemare not transmittedblocksacs_info` `redirect_info, described for H2H integration. The specific set of intermediate substates that are sent in widget HTTP notifications varies by product and method.

The merchant's backend receives only the transaction status (status, sub_status, status_description) and payment attributes. A detailed example of how 3-D Secure works in an H2H scenario is given in the sectionOne-step payment.

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:

  • Verify 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 conduct transactions on the merchant 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 processedstatussub_status.

This avoids having to re-process the same operation when re-delivering alerts.

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. Therefore, it is important that alert processing is idempotent and does not require long execution times.

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"}).

On the merchant backend side, it is recommended to implement the following processing algorithm:

  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:*(if used) 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 final (success, decline) and scenario intermediate statuses, if they are provided for the scenario;

  • if necessary, additionally receive the current status of the application through methods…​/infodescribed in the product sections.

Next steps

To configure and debug the widget: