Order Status with Settlement

This step elaborates on how you can check the status of the payment initiated.

Note : It is recommended to rely on Server to server callback response, if not received then you can start calling the check status API

Below are the APIs to check the status :

Order Status: This API is used to check the order status including the settlement related details.

Order Status API

This API is used to check the payment status with settlement details.

Complete Host URL

HTTP METHOD: GET

https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/order/<merchantOrderId>/status?settlementDetails=true

Request Details

Request Headers

Header Name	Header Value
`Content-Type`	application/json
`Authorization`	O-Bearer <merchant-auth-token>

Header details :

Content-Type – Its value should be always application/json, meaning this API responds to only when content is in format of application/json
Authorization – This should be the auth token that you have received from the Auth API.

Additional Header

Note: Applicable only for TSP/Partners only and not for Direct Merchants
X-MERCHANT-ID – End merchant’s Merchant Id for which the transaction is being initiated.

Path Parameters

Header Name	Description
`merchantOrderId`	The merchant generated Order Id

Query Parameters

Header Name	Description
`settlementDetails`	true → return the details under settlementDetails

Query the API with above details using HTTP GET method, below is the sample CURL for the same:

curl --location 'https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/v2/order/TX123rrty34432456/status?settlementDetails=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: O-Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MTIyNTM2MjU2NDQsIm1lcmNoYW50SWQiOiJWMlNVQlVBVCJ9.7aVzYI_f_77-bBicEcRNuYx093b2wCsgl_WFNkKqAPY'

Sample response of the above CURL :

Note: Merchants should rely only on the highlighted “state” parameter for the payment status confirmation.

{
    "orderId": "OMO2403282020198641071317",
    "state": "COMPLETED",
    "amount": 10000,
    "expireAt": 1711867462542,
    "paymentDetails": [
        {
            "paymentMode": "UPI_QR",
            "transactionId": "OM2403282020198651071949",
            "timestamp": 1711694662542,
            "amount": 10000,
            "state": "COMPLETED",
            "rail": {
                "type": "UPI",
                "utr": "<utr>",
                "upiTransactionId": "<upiTransactionId>",
                "vpa": "<vpa>"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "<maskedAccountNumber>",
                "accountType": "SAVINGS",
                "accountHolderName": "<accountHolderName>"
            }
        }
    ],
    "settlementDetails": {
        "state": "PROCESSED",
        "splitSettlementDetails": [
            {
                "type": "UPI",
                "settlementId": "93de5fff-fb18-4be6-ac8a-df5da3b55596",
                "utr": "UTR100298",
                "timestamp": 1723050625221,
                "amountBreakup": {
                    "transactionAmount": 10000,
                    "settlementAmount": 9998,
                    "settlementDeduction": {
                        "sgst": 0,
                        "cgst": 0,
                        "igst": 0,
                        "fee": -2,
                        "commission": 0
                    }
                }
            }
        ]
    }
}

Response Details

Response Headers:

Header Name	Header Value
`Content-Type`	application/json

Response Payload:

Order is completed and settlementDetails = true

Http Response Code: 200
Note: Merchants should rely only on the highlighted “state” parameter for the Payment status confirmation.

{
    "orderId": "OMO2403282020198641071317",
    "state": "COMPLETED",
    "amount": 10000,
    "expireAt": 1711867462542,
    "paymentDetails": [
        {
            "paymentMode": "UPI_QR",
            "transactionId": "OM2403282020198651071949",
            "timestamp": 1711694662542,
            "amount": 10000,
            "state": "COMPLETED",
            "rail": {
                "type": "UPI",
                "utr": "<utr>",
                "upiTransactionId": "<upiTransactionId>",
                "vpa": "<vpa>"
            },
            "instrument": {
                "type": "ACCOUNT",
                "maskedAccountNumber": "<maskedAccountNumber>",
                "accountType": "SAVINGS",
                "accountHolderName": "<accountHolderName>"
            }
        }
    ],
    "settlementDetails": {
        "state": "PROCESSED",
        "splitSettlementDetails": [
            {
                "type": "UPI",
                "settlementId": "93de5fff-fb18-4be6-ac8a-df5da3b55596",
                "utr": "UTR100298",
                "timestamp": 1723050625221,
                "amountBreakup": {
                    "transactionAmount": 10000,
                    "settlementAmount": 9998,
                    "settlementDeduction": {
                        "sgst": 0,
                        "cgst": 0,
                        "igst": 0,
                        "fee": -2,
                        "commission": 0
                    }
                }
            }
        ]
    }
}

Response Field Details:

Header Name	Data Type	Description
`orderId`	String	PG generated internal order id
`state`	String	State of order, Expected Values = [PENDING, FAILED, COMPLETED] Note: Merchants should rely only on the “state” parameter for the Payment status confirmation.
`amount`	String	Order amount in paisa
`expireAt`	Long	order expiry time in epoch (in milliseconds)
`metaInfo`	Object	Merchant defined meta info passed at the time of order creation
`paymentDetails`	List	Contain list of details of each payment attempt made corresponding to this order.
`paymentDetails.paymentMode`	String	Mode of payment. Expected Values = [UPI_INTENT, UPI_COLLECT, UPI_QR, CARD, TOKEN, NET_BANKING]
`paymentDetails.timestamp`	Long	Transaction attempt timestamp in epoch (in milliseconds)
`paymentDetails.amount`	Long	Amount in paisa, corresponding to payment attempt
`paymentDetails.transactionId`	String	internal transaction id for given payment attempt
`paymentDetails.state`	String	Transaction attempt state. Expected Values = [PENDING, COMPLETED, FAILED]
`paymentDetails.errorCode`	String	Error code (Only present when transaction state is failed)
`paymentDetails.detailedErrorCode`	String	Detailed Error Code (Only present when transaction state is failed)
`paymentDetails.rail`	String	Contains processing rail details under which payment attempt is made.
`paymentDetails.rail.type`	String	Type of rail. Expected values = [UPI, PG]
`paymentDetails.instrument`	String	Contains instrument details
`paymentDetails.instrument.type`	String	Type of payment instrument. Expected values = [ACCOUNT,CREDIT_CARD, DEBIT_CARD,NET_BANKING]
`settlementDetails`	Object	The settlement details of the order
`settlementDetails.state`	String	Settlement State. Expected Values = 1. NOT_INITIATED 2. INITIATED 3. PROCESSED 4. ATTEMPT_FAILED