Checking current payment information

While working with the ecommpay payment platform, you can monitor up-to-date payment processing information using 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—but not earlier than 10 seconds after the initial request to process a payment was sent.

Via the API, you can check payment status information with the use of:

• Payment ID. Use this option when you need payment information after the payment request has been accepted and the payment has been registered in the platform. In this case, the response to the payment status request contains essential information about the payment. If the payment request has not been accepted yet, for example, in case when the Payment Page was opened and the customer closed it 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.
• Request ID. Use this option if you need to check payment status information when the request has not been accepted for processing due to errors in the request. The response to such a request contains error information. However, once the payment has been registered in the platform, the preferred method of checking payment status information is by the payment identifier.

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 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.

{
    "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.

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

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).

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).

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).

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=="
}

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.

{
   "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.

• Interaction concepts—general information about integration with the payment platform using Gate.
• Payment models and statuses—detailed information about types, workflows, and possible statuses of supported payments.
• Signature generation and verification—detailed information about generating and verifying signatures in requests and callbacks sent by the payment platform.
• Information of operations performing—a comprehensive list of error and response codes used in the payment platform to provide operation processing information.