Status model and processing

This section describes the status model in the HighHelp payment gateway and the principles of their processing on the integration side. Full list of valuesstatus, sub_statusand standardstatus_descriptiongiven in sectionStatus codes.

Status fields in API responses and alerts

The following status fields are used in API responses and all alerts:

  • status— the basic status of the application or transaction.

  • sub_status— a clarifying state within the main status. The field may be empty (null).

  • status_description— text description of the status or cause of the error. The field is filled in for refusals, errors and situations where action is required on the part of the merchant.

To interpret specific values, use the sectionStatus codes.

Intermediate and final statuses

Statuses are divided into two groups:

  • Intermediate— the application is being processed, the final decision has not yet been made.

  • Final— processing is completed, the result will no longer change.

Final statuses include:

  • success— the operation is completed, the funds are successfully written off or credited.

  • decline— operation diverted.

Intermediate statuses include:

  • groupprocessing— the application is being processed, confirmed or routed;

  • groupdispute— the application requires an analysis of the problem situation;

  • statuserror— the request was rejected due to a parameter error or processing error before the business scenario was completed.

The exact set of intermediate statuses depends on the type of operation and product. A complete list is given in the sectionStatus codes. Product-specific scenarios, such as 3-D Secure, redirection, or OTP, are described in the relevant sections of the documentation.

Relationship between statuses and payment types

Operation types are described in sectionPayment types.

The same status can be used for different types of operations. For example:

  • successis also used for payments (payin), and for payments (payout).

  • processing:newused when creating any application.

  • Specialized substatuses are tied to a specific scenario and product.

Features of the life cycle of payments and disbursements via the H2H API are described in the sectionTransaction types and statuses (H2H).

Status_description field

For errors and failures, two levels of detail are used:

  • fieldsstatussub_statusfix the general type of condition.

  • Fieldstatus_descriptioncontains a text description of the reason.

Recommended:

  • use fieldsstatussub_statusfor technical processing and routing;

  • usestatus_descriptionfor logging and display in the support interface;

  • do not build business logic only on textstatus_description, if the decision can be made according tostatussub_status.

List of typical valuesstatus_descriptionand their purpose is given in the sectionStatus codes.

Recommendations for processing statuses

When integrating via API, it is recommended to adhere to the following rules:

  • When processing application status, use the fieldsstatussub_status.

  • Consider the following values ​​as statuses that complete the life cycle of an application:successdecline.

  • For intermediate statuses, do not perform business actions that cannot be rolled back until the final status is achieved.

  • Keep a log of all status changes bypayment_idrequest_idfor subsequent diagnostics.

  • Use a strong idempotency key for alerts, e.g.{project_id}:{payment_id}:{status}:{sub_status}, and protect against duplicate processing.

Additional recommendations for processing statuses in the context of H2H integration are provided in the sectionTransaction types and statuses (H2H).