How to check payment status

Overview

During the payment processing process, the payment platform conveys payment statuses in callbacks you receive from the payment platform, but sometimes you need to check the current status of specific payments. The easiest way to do this is to see the payment details in Dashboard. Alternatively, you can request the payment status programmatically by using Gate API. This section explains how to submit a request for payment status, process the response, and get the payment status from the response. Here, you will also find some examples of payment platform responses for different status request scenarios.

The payment status request is executed synchronously, in other words it completes within a single HTTP session and the payment platform responds to a well-formed request with 200 HTTP response that contains the payment status.

If the status request is not well-formed or the platform encountered some issues when processing the request, the response contains the following:

  • HTTP response code which is not 200
  • error—request processing status
  • error message with description of the cause of the error

For more information about HTTP response codes, see Integration procedure. For more information about error codes returned by the payment platform, see Operation statuses and response codes

Once you submit the initial payment request, it is recommended to wait at least 10 seconds before submitting payment status request. This time the payment platform needs to process the payment request and create the new payment. If you submit a payment status request earlier, the chances are that the payment platform will respond with an error and report that the payment as missing from the platform.

Request

Payment status request contents comply with the standard request guidelines for requests to Gate described in Integration procedure. The following is the requirement to the contents of payment status request contents.

HTTP method POST
Request body language JSON
Endpoint /v2/payment/status
Table 1. Basic payment status request parameters
Object Parameter Description

general
object
required

project_id
integer
required

 Project ID obtained from Rocketpay

payment_id
string
required

 ID of the payment whose status is requested

signature
string
required

 Signature created after you specify all the required parameters. For more information about signature generation, Signature generation and verification.)

Here is an example of payment status request body.

Figure: Payment status request example

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

Synchronous response

Response to payment status request comply with the standard request guidelines for response contents described in Integration procedure

After accepting a well-formed payment status request, the payment platform responds with response that contains status line that includes the protocol version, for example HTTP/1.1, response code, and reason phrase, for example 200 OK. The response body contains the following required information:

  • project ID
  • payment status and the details of all the operations within the payment
  • signature

Also, the response body may contain additional data; the contents of the data are agreed upon with the support specialist when integrating with Rocketpay and depend on the current payment method. The rest of this section presents examples of responses for different scenarios including payments at different processing stages, situations in which the request cannot be processed or the requested payment is missing from the payment platform.

Example 1: Response with success status for a two-step purchase

The example contains:

  • 200—response code indicating that the request was successfully accepted
  • success—payment status indicating successful payment completion
  • card—payment method code. In this case, its payment card.
  • auth and capture—operations details in the operations array

Figure: Sample response with success status for a two-step purchase

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 Elton",
    "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",                           // Auth operation status
      "message":"Success",                  // Code description
      "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 for capture operation
      "message":"Success",                // Code explanation
      "provider":{ 
        "id":615,
        "payment_id":"2015611",
        "auth_code":"7213535217",
        "endpoint_id":615,
        "date":"2019-12-12T15:46:51+0000"
      }
    }
  ],
  "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg=="
}

Example 2: Response for payment in progress

This is an example for one-step purchase in an intermediate status. The example contains:

  • 200—response code indicating that the request was successfully accepted
  • awaiting redirect result—payment status indicating that the payment waits for return after the customer was redirected to an external provider
  • mobile—payment method code
  • operations—array with the details of operations included in the payment

Figure: Sample response for one-step purchase in an intermediate status

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":"mobile",                   // Payment method code
    "sum":{ 
      "amount":25000,
      "currency":"KZT"
    },
    "description":"Book premium"
  },
  "customer":{ 
    "id":"Scott",
    "phone":"77761234567"
  },
  "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":"KZT"
      },
      "sum_converted":{ 
        "amount":25000,
        "currency":"KZT"
      },
      "code":"9999",                       // Sale operation status
      "message":"Awaiting processing",     // Code description
      "provider":{ 
        "id":2012,
        "payment_id":"",
        "auth_code":""
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}

Example 3: Response for payment missing from payment platform

The following is an example of a response to a status request for the payment which was not accepted by the payment platform for processing, for example because the customer closed the payment form and failed to confirm the payment. The response contains the following:

  • 200—response code indicating that the request was successfully accepted
  • error—payment status indicating a failure to get the payment status
  • 3061 (Transaction not found)—error code and its description indicating that the requested payment is missing from the payment platform

Figure: Sample response for missing payment

HTTP/1.1 200 OK                                  // Response status line
...                                              // Header fields
{
  "payment":{
    "status":"error"                             // Payment status
  },
  "errors":[
    {
      "code":"3061",                             // Payment status code 
      "message":"Transaction not found"          // Code description - payment not found
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

Example 4: Response for payment whose details are temporarily missing

Warning: This error does not necessarily mean the payment status is final. We strongly recommend to submit a request for the status of this payment later. Do not consider the payment completed until you get more detailed information!

The following is an example of a response in scenario in which the payment platform has accepted initial payment request, but for some reason the information about the payment is currently not available in the payment platform, for example because of transient network congestion. In this case, the response contains:

  • 200—response code indicating that the request was successfully accepted
  • error—payment status indicating a failure to get the payment information
  • error code—one of the following error codes and descriptions:
    • 3061 (Payment is not found in the system)—error code and its description indicating that the information about the payment is missing from the payment platform.
    • 3062 (Payment details not received)—error code and its description indicating that some information about the payment is missing because of transient issues in the payment platform.

Figure: Sample response for payment whose details are temporary missing

HTTP/1.1 200 OK                                 // Response status line
...                                             // Header fields
{
  "payment":{
    "status":"error"                            // Payment status
  },
  "errors":[
    {
      "code":"3062",                             // Request status code
      "message":"Payment details not received"   // Code description
    }
  ],
  "signature":"O08H+DLViSdn9ZoorYsbearslZsQ=="
}

Example 5: Response for request where parameters are missing

The following is an example of a response to a malformed request that lacks required parameters. The response contains the following:

  • 400 Bad Request—response code with the cause description in response status line.
  • error—status of the payment status request. Do not confuse with the status of the original payment initiation request!
  • 2004 and Payment details not received—error code and its description indicating that some parameters are missing from the request.

Figure: Sample response to incorrect request

HTTP/1.1 400 Bad Request                         // Response status line
...                                              // Header fields
{
   "status":"error",                             // Request processing status
   "code":"2004",                                // Request status code
   "message":"Required field not provided"       // Code explanation
}

Example 6: Response for declined purchase

Here is an example of a response with information that the payment was declined. The response contains the following:

  • 200—response code indicating that the request was successfully accepted.
  • decline—payment (purchase) status indicating that the payment was declined.
  • 20502 and Error during operation validation—error code and its description indicating that the purchase was declined.

Figure: Sample response for declined purchase

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":"johndoe@example.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",                      // Sale operation code
      "message":"Error during operation validation",    // Code description
      "provider":{
        "id":5232,
        "payment_id":"1024514",
        "auth_code":""
      }
    }
  ],
  "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow=="
}

Related links