Transaction types and statuses (H2H)

This section describes the model of operations and statuses when integrating via the H2H (host-to-host) API. The document complements the description of API methods and is intended for developers who implement payment and payout processing on their side.

General information about payment types is provided in the sectionPayment types. A complete list of statuses is described in the sectionStatus codes.

Payment and operation

The HighHelp payment gateway uses the following entities:

  • Payment— business scenario for moving funds, for example, payment for an order or payment to a user. Payment is identifiedpayment_id.

  • Operation— technical unit of processing inside the payment gateway (debit, credit, return, intermediate actions). One payment may include one or more transactions.

  • Payment type (type) — direction of movement of funds. Basic values ​​are described in sectionPayment types:

    • payin— payment (user account → merchant cash register).

    • payout— payment (merchant’s cash register → user account).

In all API methods, the request status is described by fieldsstatus, sub_statusAndstatus_description. The model of these fields is given in the sectionStatus model and processing.

Payment life cycle (payin)

The H2H payment lifecycle includes the following stages:

  1. Creating an application.

    The merchant calls the payment creation method (for example,/api/v1/payment/p2p/payinor/api/v1/payment/ecom/payin), pointingtype=payin, details and amount. The response returns the status:

    • status=processing, sub_status=new.

  2. Checking parameters and details.

    The payment gateway checks the correctness of the transferred data and the availability of providers. Intermediate statuses can be used at this stage, for example:

    • processing:requisites.

  3. Additional authentication (if required).

    Some payment scenarios may require 3-D Secure or issuer-side authentication. In this case, the statuses are used:

    • processing:awaiting_3ds_result— the result of 3-D Secure authentication is expected.

    • processing:awaiting_redirect_result- Expect authentication result when redirecting.

      Detailed operation of 3-D Secure is described in the instructions for H2H (for example,One-step payment).

  4. Final payment decision.

    Based on the results of processing, the application receives one of the final statuses:

    • success— the funds have been successfully written off and credited.

    • decline— the operation was rejected (for business reasons or by decision of the antifraud).

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

In all final statuses (success, decline) the operation is considered completed. Additional write-off attempts for the same application are not made.

Brief description of states:

  • new— the application has been accepted for processing.

  • requisites— the details are checked and routing is performed.

  • awaiting_3ds_result— the result of authentication via 3-D Secure is expected.

  • awaiting_redirect_result— the result of authentication on the issuer side is expected after the redirection.

  • processing— the funds are written off and the result is recorded.

  • success— payment is completed, funds are credited.

  • decline— payment declined. The reason can be specified in the fieldsstatus_descriptionand error code.

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

Payment life cycle (payout)

The payment life cycle includes:

  1. Creating an application.

    The merchant calls the payout creation method (for example,/api/v1/payment/p2p/payoutor/api/v1/payment/ecom/payout), pointingtype=payout, recipient details and amount. The response returns:

    • status=processing, sub_status=new.

  2. Checking balance and details.

    The payment gateway checks the available cash balance and the correctness of the details. Possible intermediate statuses:

    • processing:requisites.

  3. Execution of payment.

    After successful verification, the application changes to the status:

    • processing:payout_process— funds are transferred to the specified details.

  4. Analysis of problem situations (dispute).

    If the payment cannot be executed, group statuses are useddispute, For example:

    • dispute:incorrect_requisites— Incorrect details are specified.

    • dispute:payout_failed— the payment was not fulfilled by the provider.

    • dispute:payout_timeout— the payment is not executed before the expiration of the application’s lifetime.

      These statuses require additional processing and resolution on the merchant and/or support side.

  5. Final payment decision.

    The completion of the payment life cycle is recorded by the following statuses:

    • success— payment completed.

    • decline— payment rejected.

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

Brief description of key states:

  • new— the payment application has been accepted for processing.

  • requisites— recipient details are checked and routing is performed.

  • payout_process— funds are transferred.

  • success— payment completed.

  • decline— payment is rejected without opening a dispute.

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

  • dispute:incorrect_requisites— a dispute has been opened due to incorrect details.

  • dispute:payout_failed— dispute due to unsuccessful payment execution.

  • dispute:payout_timeout— dispute due to the expiration of payment processing time.

Dispute statuses

Dispute (dispute) describes proceedings regarding a specific payment or disbursement transaction. Below is a generalized life cycle of a dispute.

stateDiagram-v2
[*] --> opened
opened --> in_progress
in_progress --> resolved
in_progress --> declined
resolved --> [*]
declined --> [*]

Description of states:

  • opened— the dispute has been created.

  • in_progress— the dispute is being considered.

  • resolved— the dispute is closed with a recorded decision in favor of one of the parties.

  • declined— the dispute is closed without changing the result of the operation.

The statuses of disputes and their descriptions are in the sectionStatus codes.

Correspondence of merchant statuses and actions

The table below provides general recommendations for processing statuses on the merchant side.

Status group Example values Recommendations

Acceptance and processing

processing:new, processing:requisites

Record the creation of the application. Display statusin processing. Do not change the business status of the order and do not perform financial actions.

Waiting for user action

processing:awaiting_3ds_result, processing:awaiting_redirect_result

Wait for authentication to complete. If necessary, redirect the user to the issuer or 3-D Secure page. Do not write off or return funds yourself.

Execution of payment

processing:payout_process

Display statuspayment in progress. Do not duplicate payments before receiving final status.

Analysis of a problem situation

dispute:*

Record details and transmit information to support operator. Do not make repeated debits or payments until the reason is clarified.

Successful completion

success

Update order status onpaidorpayment completed. Display the result to the user. Do not perform repeated financial actions on thispayment_id.

Failed completion

decline

Update order status ondivertedor similar. Allow the user to repeat the payment or request a new payment with a new onepayment_id.

Additional examples of the status life cycle are provided in the sectionsP2PAndECOMand inStatus model and processing