Checking current payment information

Overview

While working with the ECommPay payment platform, you can monitor up-to-date payment processing information using Dashboard Light (Dashboard) and at the API level — through callbacks sent automatically according to a set of specified conditions (to learn more, see Callbacks) and responses to payment status requests. These requests can be sent whenever needed—for example, you may need to check the status of the payment made at the payment kiosk because its processing can take more than a day. However, it is important to keep in mind that payment information is available only when the request to process the payment in question has been received and the payment has been registered. Therefore, if the customer closes the Payment Page without confirming the purchase, the response to the payment status request contains an error message that this payment has not been found in the platform.

A payment status request is processed according to the synchronous model of interaction between the web server and the payment platform. 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 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 Information of operations performing.

Request format

A payment status request is formatted according to the guidelines listed in section 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: 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 section 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 ID and a signature as well as information about the payment status and all operations initiated within this payment. It can also contain additional data which is customized with the assistance of the ECommPay technical support specialists and can vary depending on the payment method used.

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 auth and capture operations contained in the operations array.

Figure: 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":"4805153025061891",
    "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"
     }
    },
    { 
      "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
      "provider":{ 
        "id":615,
        "payment_id":"2015611",
        "auth_code":"7213535217",
        "endpoint_id":615,
        "date":"2019-12-12T15:46:51+0000"
      }
    }
  ],
  "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: 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":""
      }
    }
  ],
  "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: 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: 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":""
      }
    }
  ],
  "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: 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=="
}

Related links