Create Payment Link

The Create Payment Link API allows you to generate a unique payment link that you can share with your customers. This link takes them to a secure checkout page where they can complete the transaction using UPI, cards, or NetBanking.

Use this API to initiate a payment request by providing transaction details like the payment amount, a unique Merchant order ID, and other relevant information needed to generate the payment link.

Environment

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

Request

Request Headers

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

⚠️ For Partner Integrations!

It is mandatory to include the X-MERCHANT-ID header with the MerchantID of the end merchant.

Request Parameters

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`merchantOrderId`	String	Unique merchant order ID generated by you.	Yes	Maximum length is 63 characters. Only underscore (_) and hyphen (-) are allowed as special characters.
`amount`	Long	Order amount specified in paisa.	Yes	Minimum amount = 1.
`metaInfo`	Object	Meta information means extra details you want to add for your own use. This information will be sent back to you in the status and callback responses.	No
`paymentFlow`	Object	Additional details required by this flow.	Yes

The metaInfo object contains additional parameters, which are explained in the table below.

Request Parameters of metoInfo Object:

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`metaInfo.udf1-`15	String	Optional details you can add for more information.	No	• Maximum length for Udf1-10 = 256 characters • Maximum length for Udf11-15 = 50 characters

⚠️ Do Not Rename metainfo Parameters!

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.

The paymentFlow object contains additional parameters, which are explained in the table below.

Request Parameters of paymentFlow Object:

Parameter Name	Data Type	Description	Mandatory (Yes/No)	Constraints
`paymentFlow.type`	String	Type of payment flow.	Yes	Valued allowed = [PAYLINK]
`paymentFlow.customerDetails`	Object	Stores Customers details.	Yes
`paymentFlow.customerDetails.name`	Object	Stores different merchant Urls.	No	Maximum length should be 100.
`paymentFlow.customerDetails.phoneNumber`	String	Customer Phone number.	Yes	• Allowed values: [“+9197xxxxxx89”, “97xxxxxx89”] Note: Hyphens (-) or spaces are not allowed.
`paymentFlow.customerDetails.email`	String	Customer E-mail ID	No	The email ID should follow a valid format, such as [email protected].
`paymentFlow.expireAt`	Long	The expiry time of a payment link or transaction, given as an epoch timestamp (in milliseconds).	No	• The default expiry time is set to 30 days from the current moment. • You cannot set `expireAt` to a time before now, and it must not exceed 45 days from the current time.

{
    "merchantOrderId": "<merchant_order_id>",
    "amount": 10000,
    "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>"
    },
    "paymentFlow":
    {
        "type": "PAYLINK",
        "customerDetails":
        {
            "name": "Arjun",
            "phoneNumber": "+9199231XXXXX",
            "email": "[email protected]"
        },
        "notificationChannels":
        {
            "SMS": false,
            "EMAIL": false
        },
        "expireAt": 1734109588000
    }
}

Response

Case 1: Response for Payment Link Created Successfully

{
    "orderId": "OMOxx",
    "state": "ACTIVE",                         
    "expireAt": 1734109588000,
    "paylinkUrl": "https://phon.pe/some-key"            
}

Case 2: Response for Payment Link already Exists with Same Merchant Order ID (Not in ACTIVE State)

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

Case 3: Response for Invalid Expiry Timestamp Provided (In the Past)

{
  "code": "INVALID_EXPIRY",
  "message": "Expiry cannot be greater than 30 days"
}

Case 4: Response for 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 CREATED.
`expiryAt`	Long	Order expiry date in epoch.
`paylinkUrl`	String	The URL where the customer can access the payment page and complete the transaction.

Error Response Parameters

Field Name	Data Type	Description
`code`	String	Error Code
`message`	String	Error Description

Try it yourself!

headers

body params

What’s Next?

After successfully creating a payment link request, the next step is to check the status of the payment.

Head over to the next section to learn how to check the status of payment.