Checking current payment information

Overview

While working with the ecommpay payment platform, you can monitor up-to-date payment processing information using different capabilities (to learn more, see a dedicated overview). Alongside other interfaces, specialised requests to the payment/status endpoint group of the Gate APIcan be used for this purpose. These requests allow you to promptly retrieve information about specific payments at the time that is relevant to the merchant's web service and can be deeply integrated into the service functionality.

To retrieve payment status information via the Gate API, two search options are available:

  • Search by payment ID. This is the primary option and it can be used at any time. The response content when using this option depends on whether the target payment has been registered in the platform.
    • If the payment has been registered, the response to the payment status request contains up-to-date information about the payment.
    • If the payment has not been registered (for example, when Payment Page was opened and the customer closed it without confirming the payment), the response to the payment status request contains information that the payment has not been registered.
  • Search by request ID. This is a supplementary option that, for correct information retrieval, should be used no earlier than 10 seconds after sending the request to process the target payment. Using this option can be relevant, for instance, when a payment request has not been accepted due to identified errors in the request format or content. In such cases, the response to the payment status request contains information about the errors that prevented the payment from being initiated.
Notice: Generally, searching by request ID is not recommended as a replacement for the primary search by payment ID. Retrieving information about any payment after the request has been accepted is preferably done using the payment ID.

Regardless of the search option, all payment status requests are processed according to the synchronous model of interaction between the web service and the payment platform. This implies that each such 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 without detailed request processing information. If the request is incorrect, or there have been issues with its acceptance and processing, then the response contains an HTTP response status code, request processing status error, and the detailed description of the error that occurred. To learn more about HTTP response status codes, see Interaction concepts, and to learn more about the response codes that provide information on operation processing in the payment platform, see Handling operation processing information.

Checking payment information by payment ID

Request format

A request to check payment status by payment ID is formatted according to the guidelines listed in Interaction concepts. It is sent to the endpoint /v2/payment/status, and its body must contain a general object with the following identification information:

  • project_id—a project ID assigned by ecommpay at the stage of integration;
  • payment_id—an ID of the payment to be monitored;
  • signature—a request signature generated after required parameters listed above have been specified. To learn more, see Signature generation and verification.
Figure 1. Payment status request example
{
    "general":{
       "project_id":50,
       "payment_id":"ORDER_ID_302bis",
       "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
    }
}

Response format

A response to the payment status request is formatted according to the guidelines listed in Interaction concepts. If the request has been successfully accepted and processed, the response header contains the status line indicating the protocol and its version (HTTP/1.1), the response status code and the explanatory phrase (for instance, 200 OK). The body of such response contains the following data:

  • a project identifier and a signature;
  • information about the payment status and all operations initiated within this payment;
  • additional data that can vary depending on the payment method used and can be customised for different payment methods with the assistance of the technical support specialists.

The basic set of parameters passed in the response to the payment status request is listed in the Gate API specification.

Response examples

The following response contains information about a completed two-step purchase. It includes:

  • response status code indicating that the payment status request has been successfully processed (200);
  • status of the payment in question (success);
  • code of the payment method used (card);
  • information about the auth and capture operations contained in the operations array.
Figure 2. Response with the information about a completed payment
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",                                        //payment method code
    "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 status of the auth operation
      "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":{         //object with information about the 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 status of the capture operation
      "message":"Success"                             //phrase explaining the code
    }
  ],
  "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg=="
}

The following response contains information about a one-step purchase in progress which includes:

  • response status code indicating that the payment status request has been successfully processed (200);
  • status of the payment in question (awaiting redirect result);
  • code of the payment method used (Malaysian Banks);
  • information about the sale operation contained in the operations array
Figure 3. Response with the information about a payment in progress
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",                             //payment method code
    "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 status of the sale operation
      "message":"Awaiting processing",                //phrase explaining the code
      "provider":{ 
        "id":2012,
        "payment_id":"",
        "auth_code":""
      },
      "operation_fee":{        //object with information about the operation fee
        "amount":25,
        "currency":"MYR"
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}

The following is the response to the incorrect request. If the request contains an error, the response includes:

  • response status code indicating the reason for the error that occurred (400 Bad Request);
  • request processing status (error);
  • detailed description of the error that occurred: error code (2004) and the explanatory phrase (Required field not provided).
Figure 4. Response with the information about the incorrect request
HTTP/1.1 400 Bad Request                    //response status line
...                                                  //header fields
{
   "status":"error",                                 //request processing status
   "code":"2004",                                    //code specifying the status 
   "message":"Required field not provided"           //phrase explaining the code
}

For comparison, the following is the example of the response with the information about a declined payment. This response contains:

  • response status code indicating that the payment status request has been successfully processed (200);
  • status of the payment in question (decline);
  • information about the sale operation which includes operation processing error code (20502) and the explanatory phrase (Error during operation validation).
Figure 5. Response with the information about a declined payment
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":"2018-05-04T12:55:51+0000",
    "method":"mobile",                                     //payment method code
    "sum":{
      "amount":849,
      "currency":"EUR"
    },
    "description":"Flights"
  },
  "account":{
    "number":"20072017",
    "type":"mTELE2"
  },
  "customer":{
    "id":"otokarczuk@gmail.com"
  },
  "operations":[
    {
      "id":2018416116,
      "type":"sale",                                      //operation type
      "status":"decline",                                 //operation status
      "date":"2020-05-04T12:55:51+0000",
      "created_date":"2020-05-04T12:55:10+0000",
      "request_id":"f522bie5cgu114cny46-fli56cdb35ght516sc4-2008",
      "sum_initial":{
        "amount":849,
        "currency":"EUR"
      },
      "sum_converted":{
        "amount":849,
        "currency":"EUR"
      },
      "code":"20502",           //code specifying the status of the sale operation
      "message":"Error during operation validation",  //phrase explaining the code
      "provider":{
        "id":5232,
        "payment_id":"1024514",
        "auth_code":""
      },
      "operation_fee":{        //object with information about the operation fee
        "amount":0,
        "currency":""
      }
    }
  ],
  "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow=="
}

The following example is the response to the payment status request when the payment in question has not been initiated in the payment platform (for instance, when the customer has closed the Payment Page without confirming the purchase and, thus, the request to initiate the payment has not been actually sent). In this case, the response contains:

  • response status code indicating that the payment status request has been successfully processed (200);
  • status of the payment in question (error);
  • detailed description of the error that occurred: error code (3061) and the explanatory phrase (Transaction not found).
Figure 6. Response with the information about the payment not yet initiated
HTTP/1.1 200 OK                                 //response status line
...                                                      //header fields
{
  "payment":{
    "status":"error"                                     //payment status
  },
  "errors":[
    {
      "code":"3061",                             //code specifying the status   
      "message":"Transaction not found"          //phrase explaining the code
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

Checking payment information by request ID

Request format

A request to check payment status by request ID is formatted according to the guidelines listed in Interaction concepts. It is sent to the endpoint /v2/payment/status/request, and its body must contain the following identification information:

  • project_id—a project ID assigned by ecommpay at the stage of integration;
  • request_id—an ID of the request to be monitored, can be found in the synchronous response from the payment platform;
  • signature—a request signature generated after required parameters listed above have been specified. To learn more, see Signature generation and verification.
Figure 7. Example of the request body to check payment status information
{
   "project_id":50,
   "request_id":"2336565",
   "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw=="
}

Response format

A response to the payment status request is formatted according to the guidelines listed in Interaction concepts. If the request has been successfully accepted and processed, the response header contains the status line indicating the protocol and its version (HTTP/1.1), the response status code and the explanatory phrase (for instance, 200 OK). The body of such response contains information about the payment in question: it is either the information about the payment status and all operations initiated within this payment, or the information about errors in the payment request.

Related links