Checking current payment information

While working with the Ecommpay payment platform, you can monitor up-to-date payment processing information using different capabilities (a detailed overview can be found in this article). Alongside other interfaces, you can also send including requests to the /v2/payment/status endpoint of the Gate API. These requests allow you to retrieve information about specific payments when it is relevant to your web service and can be seamlessly integrated into the service functionality.

Interaction mechanism

A payment status request is processed according to the synchronous model of interaction between the web server and the payment platform (details). This implies that the request is fully processed within one HTTP session and uses only the resources of the payment platform. The response to the correct request contains an HTTP response status code (200) and the required data.

However, for payment status requests to be processed correctly, each request must be sent by the web service no earlier than two seconds after the most recent payment action request for the payment was sent. Therefore, after initiating a payment or operation of any type (whether a purchase, cancelling an authorisation hold, refund, payout, or anything else), you must allow at least a two-second interval before checking the status of that payment. Otherwise, you will encounter errors in request processing and data retrieval.

Data categories

The response to a correct and fully processed payment status request can contain two categories of data:

• Payment data—included when the payment has been registered in the platform (and there is available information about it).

  This category is primary. It is always included in responses when applicable.

• Invalid request data—included when the last request for performing actions within the payment received by the platform was not accepted for processing, for example, due to missing or incorrectly specified required parameters (details below).

  This category is additional and recommended for use. Whether or not it should be included in responses is configured at the project level via the Ecommpay technical support.

To process these categories of data correctly, familiarise yourself with the response codes and messages that are included in payment status responses and callbacks. The list can be found in the article on handling operation processing information.

Processing payment action request data

A payment status response can only include data on the most recent request for performing a specific action within the payment. This means that if a series of payment action requests are received by the platform for the same payment, only the errors of the last received request are treated as current request errors regardless of whether the previous requests were correctly formed (hence the errors in the previous requests disregarded entirely).

This approach can be illustrated with the following examples:

1. If an invalid request for placing an authorisation hold as part of processing a two-step purchase (details) is received by the platform, the payment status response will include information about the identified errors.
2. If then an authorisation hold is initiated and completed in the platform, and a subsequent capture of the held funds is incorrectly initiated for this purchase, the payment status response will include payment data and invalid request data, with information about the errors in the request for capturing the funds.
3. If then a valid partial refund request is received by the platform for the same payment, the invalid request data for that payment will not be populated (because the most recent request is valid). To determine that the refund cannot be issued in this case because the held funds were not captured, you need to analyse the payment data.
4. If then an invalid request for the second partial refund is received by the platform for the same payment, the invalid request data for this payment will include information about the errors in the most recent partial refund request. To determine that even a valid refund request cannot be processed in this case because the held funds were not captured, you need to analyse the payment data. To determine why the most recent refund request is invalid—the invalid request data.

Under this approach, error data for any requests preceding the most recent one is considered outdated and cannot be retrieved by the web service with the use of payment status requests. For this reason, in situations where payment status requests are used as the primary means of retrieving payment information, make sure your web service:

1. Checks the status of each payment before initiating a new action within it—to avoid missing request errors and losing critically important information.
2. Sends requests for performing new payment actions only after checking the payment status and verifying whether any invalid requests exist for that payment—to avoid initiating new actions before errors from previously initiated actions have been resolved.

This approach can be illustrated as follows.

Response cases

Depending on whether the payment has been registered and whether the most recent request within it is valid, four situations and four response cases are possible.

• There is a payment; there is no request with errors.

  If the payment has been registered and there is no invalid request for it, the payment status response will contain payment data and will not contain data on errors in the most recent request received for the payment (even if this information is configured to be included in the response for the project). This is a standard situation: it indicates that the platform has accepted the request to process the payment and any additional action requests for it (if applicable and initiated by the web service).

  In this case, an appropriate course of action is to analyse the payment status and the statuses of its associated operations and proceed as normal based on those statuses.

• There is a payment; there is a request with errors.

  If the payment has been registered and there is an invalid request for it, the payment status response will contain payment data and, if it was configured for the project, will contain data on errors in the most recent request received for the payment. This situation indicates that the platform received a valid request to process the payment, but subsequent payment processing was halted due to an additional request with critical errors: for example, a refund request with an amount that exceeds the initial payment amount.

  In this case, an appropriate course of action is to analyse the error data for the request and resend it as a corrected request if applicable.

• There is no payment; there is no request with errors.

  If the payment has not been registered and there is no invalid request for it, the payment status response will contain neither payment data nor data on errors in the most recent request received for the payment (even if this information is configured to be included in the response for the project) because no such data is available in the platform. This situation indicates that the platform received no requests to process this payment, for example, due to a failure when the payment processing request was sent, or because the payment status request contained an incorrect payment identifier that had not been previously used within the given project.

  In this case, an appropriate course of action is to verify the validity of the original payment status request, correct it if necessary, and retry at intervals of at least two seconds. If the retries are unsuccessful, try re-initiating the payment (with the same identifier) or contact the Ecommpay technical support. The recommended actions for such situations are described in greater detail below.

• There is no payment; there is a request with errors.

  If the payment has not been registered and there is an invalid request for it, the payment status response will contain a limited set of payment data and, if it was configured for the project, will contain data on errors in the most recent request received for the payment. This situation indicates that the platform received a request to process the payment, but this request contained critical errors, for example, the required data was not provided, due to which the payment was assigned the error status in the platform.

  In this case, an appropriate course of action is to analyse the error data for the payment processing request and, if applicable, re-initiate the payment by sending a corrected request with the same payment identifier in the payment_id parameter as in the original request.

If there are errors in a payment status request or errors during its processing, the response will contain the relevant HTTP code (for example, 400) and data on the identified errors. In this case, an appropriate course of action is to analyse the error data for the request and resend a corrected payment status request if applicable.

Examples of responses for all of the situations listed above, with invalid request data, are provided below.

When interpreting the information in the payment status responses, keep in mind the following:

• Any payment request related data is included in a payment status response only after the relevant request has been accepted and processed in the platform. This means that even after a request has been received by the platform, there is a time lag before the information about this request and the payment or operation it initiates can be included in a payment status response.
• To ensure correct processing of payment status requests and receiving up-to-date and complete information in payment status responses, it is important that you maintain a two second interval between sending a payment request and sending a subsequent payment status request. In some cases, if you need to resend the request, you may need to wait even longer. More detailed recommendations for working with payment status requests can be found below.

To receive payment status information via the Gate API, send a request to the /v2/payment/status endpoint. A payment status request is formatted according to the guidelines listed in the article about interaction principles, and its body must contain with the general object with the following information identifying the payment and signature:

• project_id—a project identifier assigned by Ecommpay
• payment_id—an identifier of the payment to be monitored
• signature—a request signature generated after all required parameters listed above have been specified (details)

{
    "general":{
       "project_id":50,
       "payment_id":"ORDER_ID_302bis",
       "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}

Overview

A response to the payment status request is formatted according to the guidelines listed in the article about interaction principles, while its contents as far as included objects and parameters are concerned can vary, as it is determined by the specifics of the payment platform operation. It is essential that the web service correctly handles responses with different structures. This applies primarily to information on payment operations and on errors in the most recent request (more below).

The header of a payment status response includes a status line specifying the protocol and its version (HTTP/1.1), the response code, and an explanatory phrase (for example, 200 OK for a response containing payment data or 400 Bad Request for a response indicating an invalid payment status request), followed by additional lines containing technical information as defined by the protocol used.

The body of a payment status response may include various data depending on the validity of the request and other factors. The key objects and parameters, as well as different ways of representing similar types of information in such responses, are described further in this section. The complete set of data that can be returned in payment status responses in the default configuration is provided in the Gate API specification. In coordination with technical support specialists, the set and names of objects and parameters can also be modified for individual projects.

Examples of responses for various situations are provided below, in a separate section of this article.

Payment status data composition

If a payment status request was correctly sent by the web service and correctly processed by the platform, the response body includes:

• The project identifier and the response signature—in the project_id and signature parameters, respectively.
• The payment status—in the status parameter.
• Information about the most recent payment action request—in the last_failed_request object—when both of the following conditions are met:
  • The project is configured to include such information in payment status responses.
  • The most recent request for the payment was received but was not accepted for processing in the platform due to identified errors.
• Information about operations executed within this payment—either about the most recently initiated operation in the operation object, or about all initiated operations in the operations array (depending on the specifics of the project and the payment).

  Keep in mind that the operation object and the operations array can be treated as equally significant, and responses to status requests for the same payment may present information first in one form and then in the other. The web service must therefore ensure correct handling of both formats.

• Additional payment data—in objects and parameters whose composition may vary depending on the payment type and status, the payment method, and other different factors and can be configured in coordination with technical support specialists.

Invalid request data composition

If a payment status request is identified as invalid or a problem occurs while it is processed, the response body can include two types of error data:

• Basic error data (can be used for all responses, including those with codes 400, 403, 422, and 500)—with the following parameters:
  • status—the processing status of the payment status request (error)
  • code—the code of the error that occurred (as a string, data type string)
  • message—an explanatory phrase for the specified code
  Note: When analysing errors, keep in mind that in cases when there is a problem with processing a payment status request, the status parameter is not included in the payment object and relates not to the payment itself but only to the payment status request.
• Extended error data with details about specific input fields (which can be used for responses with code 400)—as an errors array, in which the following parameters can be specified for each field-related error:
  • code—the code of the error that occurred (as a number, data type integer)
  • message—an explanatory phrase for the specified code
  • field—the full name of the parameter that was filled in incorrectly
  • constraint—a brief description of the constraint or requirement that was not met when the parameter was specified

Registered payments without invalid requests

For registered payments without invalid requests, a payment status response includes payment data and does not include data on errors in the most recent request received for the payment (even if its use is configured for the project).

HTTP/1.1 200 OK                                             // response status line
...                                                         // header fields
{ 
  "project_id":72,
  "payment":{ 
    "id":"ORDER_ID_tetan_M_2007_2012",
    "type":"purchase",                                       // payment type
    "status":"awaiting redirect result",                     // payment status
    "date":"2019-12-11T15:59:10+0000",
    "method":"Malaysian Banks",
    "sum":{ 
      "amount":25000,
      "currency":"MYR"
    },
    "description":"Book premium"
  },
  "customer":{ 
    "id":"Scott",
    "phone":"44177118324"
  },
  "operations":[ 
    { 
      "id":65747461,
      "type":"sale",                                           // operation type
      "status":"awaiting redirect result",                     // operation status
      "date":"2019-12-11T15:59:10+0000",
      "created_date":"2019-12-11T15:59:06+0000",
      "request_id":"97c7dd03080b4293603f28e64-0c415bc3e876c911f2d87-00006979",
      "sum_initial":{ 
        "amount":25000,
        "currency":"MYR"
      },
      "sum_converted":{ 
        "amount":25000,
        "currency":"MYR"
      },
      "code":"9999",                       // code specifying the operation status
      "message":"Awaiting processing",     // phrase explaining the code
      "provider":{ 
        "id":2012,
        "payment_id":"",
        "auth_code":""
      },
      "operation_fee":{
        "amount":25,
        "currency":"MYR"
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}

In this example, the response indicates that the payment status request was accepted, and at the time the response was generated, processing of the payment and the corresponding debiting of funds were suspended until the information from the customer redirection is received.

In this example, the response indicates that:

• The payment status request was accepted (response code 200).
• Processing of the payment was suspended until the information from the customer redirection is received (the purchase payment has the status awaiting redirect result).
• For the debiting of funds initiated as part of this payment, the platform is awaiting information from the customer redirection (the sale operation in the operations array has the status awaiting redirect result).

In this situation, you can expect information from the customer redirection and, if applicable given the interface and payment method, submit the required data to the platform once this information is received on the web service side.

HTTP/1.1 200 OK                                     // response status line
...                                                 // header fields
{
  "project_id":912103,
  "payment":{
    "id":"ORDER_ID_2018nbl",
    "type":"purchase",                              // payment type
    "status":"decline",                             // payment status
    "date":"2026-05-04T12:55:51+0000",
    "method":"card",
    "sum":{
      "amount":849,
      "currency":"EUR"
    },
    "description":"Flights"
  },
  "customer":{
    "id":"john_doe@example.com"
  },
  "operations":[
    {
      "id":2018416116,
      "type":"sale",                           // operation type
      "status":"decline",                      // operation status
      "date":"2026-05-04T12:55:51+0000",
      "created_date":"2026-05-04T12:55:10+0000",
      "request_id":"f522bie5cgu114cny46-fli56cdb35ght516sc4-2008",
      "sum_initial":{
        "amount":849,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":849,
        "currency":"EUR"
      },
      "code":"10114",                         // code specifying the operation status
      "message":"Declined by 3DS Check",      // phrase explaining the code
      "provider":{
        "id":5232,
        "payment_id":"1024514",
        "auth_code":""
      },
      "operation_fee":{
        "amount":0,
        "currency":""
      }
    }
  ],
  "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow=="
}

In this example, the response indicates that the payment status request was accepted, but the payment and the corresponding debiting of funds were declined due to the unsatisfactory customer authentication result.

In this example, the response indicates that:

• The payment status request was accepted (response code 200).
• The payment was declined (the purchase payment has the status decline).
• The debiting of funds initiated as part of this payment was declined due to the unsatisfactory customer authentication result (the sale operation in the operations array has the status decline, with status code 10114 and the description Declined by 3DS Check).

To process the payment in this case, notify the customer why the previous payment attempt was declined (based on the authentication result) and, if the customer is ready to make another attempt, initiate a new payment (with a new identifier)—preferably allowing the customer to choose a different payment method or instrument.

HTTP/1.1 200 OK                                           // response status line
...                                                       // header fields
{ 
  "project_id":50,
  "payment":{ 
    "id":"ORDER_ID_302bis",
    "type":"purchase",                                     // payment type
    "status":"success",                                    // payment status
    "date":"2019-12-12T15:46:51+0000",
    "method":"card",
    "sum_real":{ 
      "amount":33,
      "currency":"USD"
    },
    "description":"Booking"
  },
  "customer":{ 
    "id":"6361696170"
  },
  "account":{ 
    "number":"4314220000000056",
    "type":"visa",
    "card_holder":"Michael Nurenberg",
    "expiry_month":"03",
    "expiry_year":"2024"
  },
  "operations":[ 
    { 
      "id":9435219675496,
      "type":"auth",                                          // operation type
      "status":"success",                                     // operation status
      "date":"2019-12-11T15:46:37+0000",
      "created_date":"2019-12-11T15:46:35+0000",
      "request_id":"bcRFZRJkmfcf-178c3d843c99-00009436",
      "sum":{ 
        "amount":33,
        "currency":"USD"
      },
      "code":"0",                           // code specifying the operation status
      "message":"Success",                  // phrase explaining the code
      "eci":"07",
      "provider":{ 
        "id":615,
        "payment_id":"2015611",
        "auth_code":"7213535217",
        "endpoint_id":615,
        "date":"2019-12-11T15:46:36+0000"
     },
      "operation_fee":{
        "amount":31,
        "currency":"USD"
      }
    },
    { 
      "id":9435219671141,
      "type":"capture",                                        // operation type
      "status":"success",                                      // operation status
      "date":"2019-12-12T15:46:51+0000",
      "created_date":"2019-12-12T15:46:48+0000",
      "request_id":"2f114083cfb0f6d12c2-2ac890ebadb793-05015382",
      "code":"0",                         // code specifying the operation status
      "message":"Success"                 // phrase explaining the code
    }
  ],
  "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg=="
}

In this example, the response indicates that the payment status request was accepted, the payment was completed, and both the authorisation hold and the capture of funds for this payment were performed.

In this example, the response indicates that:

• The payment status request was accepted (response code 200).
• The payment was completed (the purchase payment has the status success).
• The authorisation hold and capture of funds initiated as part of this payment were performed (the auth and capture operations in the operations array have the status success).

In this situation, you can record that the payment was completed and conclude the work of the web service on it.

Registered payments with invalid requests

For registered payments with invalid requests, a payment status response includes payment data and, if configured for the project, data on errors in the most recent request received for the payment.

HTTP/1.1 200 OK                                  // response status line
...                                              // header fields
{
     "last_failed_request":{     // data on the most recent payment action request
	  "id":"75227d07287cc87fa87901ddc9fc11225...",      // request identifier
	  "type":"refund",                                  // initiated operation type
      "errors": [                               // data on errors in the request
	  {
      "code": "3283",                                      // error code
      "message": "Refund amount more than initial amount"  // phrase explaining the code
	  }
    ]
    },
    "operation":{                            // data on the operation performed earlier
        "sum_initial": {
            "amount": 100,
            "currency": "GBP"
        },
        "sum_converted": {
            "amount": 100,
            "currency": "GBP"
        },
        "eci": "02",
        "provider": {
            "id": 6,
            "payment_id": "17770306686380",
            "auth_code": "563253",
            "endpoint_id": 6,
            "date": "2026-05-27T14:19:19+0000"
        },
        "id": "74000014368",
        "type": "sale",                      // operation type
        "status": "success",                 // operation status
        "date": "2026-05-27T14:19:19+0000",
        "created_date": "2026-05-27T14:19:19+0000",
        "request_id": "64cfe0272c-e220ed1b035f60da..."  // request identifier
    },
    "customer": {
        "id": "1"
    },
    "account": {
        "number": "400000******0077"
    },
    "project_id": 432037,
    "payment": {
        "id": "27052026_1",
        "type": "purchase",                  // payment type
        "status": "success",                 // payment status
        "description": "description",
        "date": "2026-05-27T14:19:19+0000",
        "method": "card",
        "sum": {  
           "amount": 100,                     // payment amount
           "currency": "GBP"
        }
    },
   "signature":"yb9JpzzbyEbsdfsdfs+c+0nX7PQwO8TPosdfsdfsPlanEYqj1SAg=="
}

In this example, the response indicates that the payment status request was accepted, the payment was completed and the corresponding debiting of funds was performed, but a refund request for this payment was not accepted for processing due to an incorrectly specified amount.

In this example, the response indicates that:

• The payment status request was accepted (response code 200).
• The payment was completed (the purchase payment has the status success).
• the debiting initiated as part of this payment was performed (the sale operation in the operation object has the status success).
• the refund request for this payment was not accepted for processing due to an incorrectly specified amount (the last_failed_request object contains an errors array with error data, code 3283 and the description Refund amount more than initial amount).

To correct the error in this case, send a new refund request specifying a valid amount (not exceeding the current payment amount, in this case 100 GBP).

Unregistered payments without invalid requests

For unregistered payments without invalid requests, a payment status response includes neither payment data nor data on errors in the most recent request received for the payment (even if their use is configured for the project)—since no such data exists in the platform.

HTTP/1.1 200 OK                                       // response status line
...                                                   // header fields
{
  "payment":{
    "status":"error"                             // payment status
  },
  "errors":[                                     // data on errors in the request
    {
      "code":"3061",                             // error code
      "message":"Transaction not found"          // phrase explaining the code
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

In this example, the response indicates that the payment status request was accepted, but no information on the payment was found in the platform.

In this example, the response indicates that:

• The payment status request was accepted (response code 200).
• No information on the payment was found in the platform (the payment object has the status error and an errors array with error data, code 3061 and the description Transaction not found).

In this situation, verify the validity of the original payment status request, correct it if necessary, and retry at intervals of at least two seconds. If the retries are unsuccessful, try re-initiating the original payment (with the same identifier) or contact the Ecommpay technical support (details). More detailed guidance on the recommended actions for such situations is provided below.

Unregistered payments with invalid requests

For unregistered payments with invalid requests, a payment status response includes a limited set of payment data and, if configured for the project, data on errors in the most recent request received for the payment.

HTTP/1.1 200 OK                                       // response status line
...                                                   // header fields
{
  "project_id": 432037,
  "payment": {
    "id": "27052026_1",
    "status": "error",                           // payment status
    "sum": { 
      "amount": 100, 
      "currency": "USD" 
    }
  },
  "errors": [                                    // data on errors in the request
    {
      "field": "booking_info.start_date",
      "code": "3201",                                      // error code
      "message": "booking_info.start_date cannot be empty" // phrase explaining the code
    }
  ],
  "operation": {                                 // operation data
    "code": "702",                               // status code
    "message": "Malformed request",              // phrase explaining the code
    "type": "sale",                              // operation type
    "status": "decline",                         // operation status
    "request_id": "64cfe0b0acfc1b6272c-e220ed127d4..."         // request identifier
  },
  "signature": "Wkq6GqjEs4w59CxXoR16gLrfrtSnjc7evr..."
}

In this example, the response indicates that the payment status request was accepted, but the payment was not registered in the platform due to a field-filling error.

In this example, the response indicates that:

• The payment status request was accepted (response code 200).
• The payment was not registered in the platform (the payment object has the status error).
• the payment processing request contained one field-filling error (the errors array contains a single object with the full parameter name booking_info.start_date, error code 3201, and the description booking_info.start_date cannot be empty).

To correct the error in this case, you can send a new request to initiate the payment specifying the same payment identifier in the payment_id parameter as in the original request, along with the start date of the booked service in the start_date parameter of the booking_info object.

Errors with payment status requests

For errors in payment status requests or errors during their processing, a response includes the corresponding HTTP code and data on the identified errors.

HTTP/1.1 400 Bad Request                         // response status line
...                                              // header fields
{
   "status":"error",                             // request processing status
   "code":"2004",                                // error code
   "message":"Required field not provided"       // phrase explaining the code
}

In this example, the response indicates that the payment status request was not accepted because required parameters were not specified in the request.

In this example, the response indicates that:

• The payment status request was not accepted (response code 400)
• Required parameters were not specified in the request (the request has the status error, with error code 2004 and the description Required field not provided).

To correct the error in this case, generate and send a new payment status request with the required parameters correctly specified, in accordance with the format.

General monitoring guidelines

To ensure effective monitoring of payment statuses using requests to the platform via the Gate API, follow the recommendations below.

1. Set up handling of synchronous responses and, where applicable, callbacks sent from the platform (more details in the articles on interaction principles and handling callbacks).

   Working with callbacks lets you receive information on significant platform events during payment processing as quickly as possible in all standard situations. By comparison, payment status requests can serve as an alternative or a supplementary method for monitoring payment statuses, depending on the specifics of your web service.

2. Set up handling of operation status codes and descriptions (details).

   These codes and descriptions are used extensively in the platform, including payment status responses, and responding to this information correctly enables you to resolve many issues that arise during payment processing quickly and efficiently.

3. Arrange for invalid payment request data to be included in payment status responses (by contacting the Ecommpay technical support).

   This allows you to receive more detailed information in payment status responses and quickly identify and correct the errors that result in payment action requests not being accepted for processing in the platform.

4. Define rules for sending payment status requests that ensure you receive the necessary payment information in a timely manner, in line with the specifics of your web service.

   These rules should clearly define the situations in which payment status requests must be sent (for example, after initiating payments of certain types, or after initiating certain payment actions from the side of the web service). Keep in mind that for any payment, you must allow an interval of at least two seconds from the moment a payment processing or payment action request is sent, so that the information you receive reflects the platform's initial processing of that request (otherwise, errors in request processing may occur).

5. Set up correct handling of the information received in payment status responses.
   1. If there is no error data, continue operating as normal.
   2. If there is error data, clearly distinguish between two categories of errors:
      • Errors relating to payment status requests (when the HTTP code of the payment status response is not 200 and the response body contains error data for the request).
      • Errors relating to the payments and the payment action requests for them (when the HTTP code of the payment status response is 200 and the response body contains error data for the payment).
   3. If you receive error data relating to payment status requests, correct these requests (when applicable) and resend them.
   4. If you receive error data relating to the payments and the payment action requests for them, analyse the content of the responses and take the appropriate action, including notifying customers and resending payment action requests when applicable (details).
      Warning: When resending payment action requests, avoid duplicating payments and operations such as partial refunds, which may be mistakenly initiated more than once and completed without any technical errors. In such situations, the merchant is responsible for any duplicate actions.

      Given these risks, it is critically important that you obtain and correctly interpret the status information for the payment and its operations before initiating any repeat action.

   5. If you receive a response indicating that no information about the requested payment is available in the platform, follow the procedure described below.

A general workflow of handling of the payment status responses can be illustrated as follows.

Examples of responses containing different types of errors are provided in the corresponding section.

Responding to missing payment data

In certain cases, a payment status response may indicate that no relevant information was found in the platform for the payment. This may occur, for example, if the payment was not registered in the platform or if another failure occurred.

HTTP/1.1 200 OK                                       // response status line
...                                                   // header fields
{
  "payment":{
    "status":"error"                             // payment status
  },
  "errors":[                                     // data on errors in the request
    {
      "code":"3061",                             // error code
      "message":"Transaction not found"          // phrase explaining the code
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

In such situations, it is recommended that you proceed as follows.

1. Make sure that the original payment status request specified the correct project and payment identifiers (a payment with the identifiers in question needs to have been previously initiated by the web service).
2. Depending on the result of the check in step 1, do one of the following:
   1. If an error in the identifiers was found, generate and send a new request with the corrected parameters.
   2. If no error in the identifiers was found, wait for at least two seconds and resend the request with the original parameters.
3. If step 2 does not return information on the payment, make further retries at intervals of at least two seconds—until either a successful attempt returns the information you need, or the maximum number of attempts defined by the web service is reached (as a general guideline, no more than ten attempts is recommended).
4. If step 3 does not return information on the payment, and the situation allows the payment to be re-initiated, resend the payment processing request (using the same identifier), confirm that a synchronous response acknowledging acceptance of the request has been received, and continue working with this payment as normal.
5. If the previous steps do not return information on the payment and it cannot be re-initiated, notify the customer of technical issues with processing the payment, contact the Ecommpay support specialists, and agree on the appropriate course of action with them, including the possibility of initiating a new payment in place of the original one.
   Warning: To avoid duplicate payments, do not initiate new payments (with new identifiers) in place of those for which information could not be obtained, until this has been agreed with the Ecommpay technical support.

Re-initiating operations

When working with payments and operations within them, mind the difference between two scenarios involving repeated requests:

• Regardless of whether a payment initiated earlier has been registered in the platform, resending a request to perform it with the same identifier in the payment_id parameter does not result in duplication (since if a payment with that identifier has already been registered, a new request to perform it is declined and does not affect the payment's state in any way).
• In situations when a payment has been registered in the platform, re-initiating an operation within it may lead to duplicate actions (since it can be interpreted as a subsequent operation on the payment, for example, in cases involving partial refunds). Therefore, before you re-initiate any actions within a payment, it is critically important to obtain and correctly interpret information about the status of this payment and its operations..

In situations when you may need to re-initiate a specific operation within a payment, it is recommended you proceed as follows:

1. Obtain information about the status of the payment.

   To do this, make sure that at least two seconds have passed since the most recent payment action request was sent, send a request to retrieve the payment status, and confirm that you receive a valid response. If the response contains error data, correct the request (if needed) and resend it.

2. Analyse the operation data received for the payment and determine whether it includes the operation you intend to re-initiate.

   To do this, check whether there is information about an operation of the relevant type (for example, capture or refund) with the initially requested amount and currency.

3. Perform one of the following actions depending on the outcome of the analysis in step 2:
   1. If information on the operation you need is found and that operation has a final status (success or decline), respond according to the operation status.

      For a performed operation (with the status success), do not initiate any further action. For a declined operation (with the status decline), determine the reason for the decline and, if this is allowed given the reason and your web service's workflow, re-initiate the operation.

   2. If information on the operation is found and that operation has an intermediate status (for example, processing or awaiting clarification), respond according to the operation type and status.

      For some intermediate statuses, it is enough for the web service to wait for a period of time before retrieving the payment status again (returning to step 1). For others, the web service needs to collect and send additional data to the platform. Information about such actions can be found in the payment processing model and in the descriptions of payment methods.

   3. If information on the operation is not found, but the response contains invalid request data, correct the errors indicated and send the corrected request.

      This response indicates that the most recent request was received and processed, but was not accepted for processing, and can be retried without risk of duplicating the operation.

   4. If the response contains no information about either the operation or an invalid request, wait for an additional ten seconds, repeat steps 1 and 2, and if the same result is obtained, resend the request, provided the web service is ready to re-initiate the operation.

      This response indicates that, at the time when it was generated, the most recent request had not reached the platform. Following this repeated verification, it is acceptable to retry the request, given the low risk of duplicating the operation due to communication channel issues or other factors.

This procedure can be illustrated as follows.

If you have any questions regarding any of the situations described above, you can contact the Ecommpay technical support.