Initiate Payment

This API is used to initiate a Payment Gateway Checkout session by providing transaction details such as the amount, order ID, and redirect URLs.

Once the request is successfully created, a checkout session is generated where the customer is redirected to complete the payment.

API Endpoints

Environment	HTTP Method	API
Sandbox	`POST`	https://api-preprod.phonepe.com/apis/pg-sandbox/checkout/guvnl/pay
Production	`POST`	https://api.phonepe.com/apis/pg/guvnl/checkout/pay

Request

Request Headers

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

Request

Sample Request

{
  "merchantOrderId": "TX123653456743456",
  "amount": 1000,
  "expireAfter": 1200,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": ""
    }
  },
  "disablePaymentRetry": true,
  "metaInfo": {
    "udf1": "additional-information-1",
    "udf2": "additional-information-2",
    "udf3": "additional-information-3",
    "udf4": "additional-information-4",
    "udf5": "additional-information-5",
    "udf6": "additional-information-6",
    "udf7": "additional-information-7",
    "udf8": "additional-information-8",
    "udf9": "additional-information-9",
    "udf10": "additional-information-10",
    "udf11": "additional-information-11",
    "udf12": "additional-information-12",
    "udf13": "additional-information-13",
    "udf14": "additional-information-14",
    "udf15": "additional-information-15"
  }
}

Sample Request with Selected Instrument for enabledPaymentModes

{
    "merchantOrderId": "TX123456",
    "amount": 1000,
    "expireAfter": 1200,
    "paymentFlow": {
        "type": "PG_CHECKOUT",
        "message": "Payment message used for collect requests",
        "merchantUrls": {
            "redirectUrl": ""
        },
        "disablePaymentRetry": true,
        "paymentModeConfig": {
            "enabledPaymentModes": [
                {
                    "type": "UPI_INTENT"
                },
                {
                    "type": "UPI_QR"
                },
                {
                    "type": "NET_BANKING"
                },
                {
                    "type": "CARD",
                    "cardTypes": [
                        "DEBIT_CARD",
                        "CREDIT_CARD"
                    ]
                }
            ]
        }
    },
    "metaInfo": {
        "udf1": "additional-information-1",
        "udf2": "additional-information-2",
        "udf3": "additional-information-3",
        "udf4": "additional-information-4",
        "udf5": "additional-information-5",
        "udf6": "additional-information-6",
        "udf7": "additional-information-7",
        "udf8": "additional-information-8",
        "udf9": "additional-information-9",
        "udf10": "additional-information-10",
        "udf11": "additional-information-11",
        "udf12": "additional-information-12",
        "udf13": "additional-information-13",
        "udf14": "additional-information-14",
        "udf15": "additional-information-15"    
    }
}

Sample Request with Selected Instrument for disabledPaymentModes

{
    "merchantOrderId": "TX123456",
    "amount": 1000,
    "expireAfter": 1200,
    "paymentFlow": {
        "type": "PG_CHECKOUT",
        "message": "Payment message used for collect requests",
        "merchantUrls": {
            "redirectUrl": ""
        },
        "disablePaymentRetry": true,
        "paymentModeConfig": {
            "disabledPaymentModes": [
                {
                    "type": "UPI_INTENT"
                },
                {
                    "type": "UPI_QR"
                },
                {
                    "type": "NET_BANKING"
                },
                {
                    "type": "CARD",
                    "cardTypes": [
                        "DEBIT_CARD",
                        "CREDIT_CARD"
                    ]
                }
            ]
        }
    },
    "metaInfo": {
        "udf1": "additional-information-1",
        "udf2": "additional-information-2",
        "udf3": "additional-information-3",
        "udf4": "additional-information-4",
        "udf5": "additional-information-5",
        "udf6": "additional-information-6",
        "udf7": "additional-information-7",
        "udf8": "additional-information-8",
        "udf9": "additional-information-9",
        "udf10": "additional-information-10",
        "udf11": "additional-information-11",
        "udf12": "additional-information-12",
        "udf13": "additional-information-13",
        "udf14": "additional-information-14",
        "udf15": "additional-information-15"    
    }
}

Request Parameters

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`merchantOrderId`	String	Unique merchant order ID generated by you	Yes	Max Length = 63 characters No Special characters are allowed except underscore “_” and hyphen “-“
`amount`	BigDecimal	The total amount for the order, in rupees (e.g., ₹1000)	Yes	Minimum value = ₹1
expireAfter	Long	The time (in seconds) after which the order will expire. If not provided, the default value will be used	No	Minimum value = 300, maximum value = 3600 (in seconds)
`metaInfo`	Object	Merchant defined meta info to store additional information. same data will be returned in status and callback response.	No	• For udf1 to udf10, there is no constraint and Maximum length for Udf1-10 = 256 characters • For udf11 to udf15, alphanumeric values with _-+@. are allowed and Maximum length for Udf11-15 = 50 characters • It is mandatory to keep the parameter names `udf1`, `udf2`, etc., exactly as they are in the `metainfo` block. Renaming these key values will result in a production error.
`paymentFlow`	Object	Additional details required by this flow	Yes
`paymentFlow.type`	String	Type of payment flow	Yes	Valued allowed=[PG_CHECKOUT]
`paymentFlow.merchantUrls`	Object	The object for storing different merchant URLs	Yes
`paymentFlow.merchantUrls.redirectUrl`	String	URL where the user will be redirected after a successful/failed payment	Yes
`prefillUserLoginDetails`	String	User phone number for prefilling in login flows	Yes

Response

Case 1: Order created successfully

{
    "orderId": "OMO123456789",
    "state": "PENDING",
    "expireAt": 1703756259307,    
    "redirectUrl": "https://mercury-uat.phonepe.com/transact/uat_v2?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcmVzT24iOjE3MjgyNTk1MzE0NzgsIm1lcmNoYW50SWQiOiJWUlVBVCIsIm1lcmNoYW50T3JkZXJJZCI6Ik1PLTlkMC1hNmMyYmY1ZWM4MmUifQ.Trj5fub__kJpQhzOlJttXl2UPruHE7fsbH5QWj-iy6E"
}

Case 2: Order with same merchant order id is already present and not in CREATED state

{
    "code": "BAD_REQUEST",
    "message": "Please check the inputs you have provided."
}

Case 3: Internal Server Error

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

Response Parameters

Field Name	Data Type	Description
`orderId`	String	Payment Gateway generated internal order ID.
`state`	String	State of the order created, expected value is PENDING.
`expireAt`	Long	Order expiry date in epoch.
`redirectUrl`	String	URL where you are supposed to redirect the user to complete payment.

Try a Sample Create Payment Request!

headers

body params