API Integration
The steps to integrate the Custom Checkout Page on the merchant’s website.
Step 1. Initiating Payment request
Step 2. Redirecting User to complete the Payment
- For Cards and Net Banking
- For UPI Intent
Step 3. Redirecting user to Merchant web page
- For Cards and Net Banking
- For UPI Intent
Step 4. Status verification post redirection to merchant website
Step 5. Handling Payment Success, Pending and Failure
Step 6. Refund
Step 1. Initiating Payment request
For UPI Intent(Only)
- [MANDATORY] The list of UPI Apps installed in the user’s device should be fetched and listed on the Checkout Page under the UPI section.
- [MANDATORY] The package name of the UPI app selected by the user should be passed in the PAY API request payload.
The merchant does a server-to-server call to initiate a payment request (PAY API). In response to this PAY API call, a URL for that particular transaction is returned to process the payment.
Refer here for PAY API – Pay Page
Step 2. Redirecting User to complete the Payment
For Cards and Net Banking
The merchant does a client-side redirection to the URL returned in Step 1. This will take the customer to the respective Bank Page for processing the payment using Cards/Net Banking.
For UPI Intent
The merchant will launch the UPI Intent URL received in Step 1 on the client side. This will launch the UPI Intent to process the payment using the respective UPI selected by the user on the merchant’s checkout page.
Step 3. Redirecting user to Merchant web page
For Cards and Net Banking
Once the user has completed the payment, PhonePe will redirect to the redirectUrl passed in the request body to give the UI control back to the merchant website.
For UPI Intent
Once the user has completed the payment, PhonePe will automatically give the control back to the merchant app.
Step 4. Status verification post redirection to merchant website
The merchant should check with their server if the S2S response is received.
Refer here for Server-to-Server Callback
- If S2S is received, the checksum and amount should be validated on the server side and the payment status has to be updated on the merchant website.
- If S2S is not received, then the PG Check Status API should be called and the amount should be validated in the response. The order status should be updated based on the transaction status provided by PhonePe.
Refer here for Check Status API
Step 5. Handling Payment Success, Pending and Failure
The S2S callback or PG Status API response will return the actual payment status. The payment status falls within these three categories and merchants should handle it.
- Payment Success
If success response is received in merchant’s server, then the success status has to be passed to the website and notify the customer with Payment Success page. - Payment Failure
If failure response is received in merchant’s server, then the failure status has to be passed to the website and notify the customer with Payment Failure page & ask the customer to retry payment. - Payment Pending
If pending response is received in merchant’s server, then the merchant can handle it in two ways depending on the use case.- Option 1: Pending status can be passed to the website and notify the customer with Payment Pending page. Ask the customer to wait for the terminal status and the status of the transaction should be shown in the order history page.
- Option 2: Even though the payment status is Pending, Failure status can be passed to the website and notify the customer with Payment Failure page along with the refund message(If any amount is debited, the amount will be refunded back).
Step 6. Refund
In case of cancellations or returns, the merchant can initiate a refund through Dashboard or Refund API. This refund will be done against the originalTransactionId (The actual transaction id of the forward payment). Refer here for the Refund API
Refer here for Refund API