Merchant Checklist

UAT Sign-Off Process

• Once the integration is completed, Merchants must share the UAT instance for the end-to-end flow verification.
  
• Any issues identified in the UAT stage must be fixed and verified by the integration POC in the UAT itself.
  
• Only if all the use cases are handled properly, the integration POC will provide the UAT Sign-off and it should be acknowledged by the Merchant to proceed further and release the Production Credentials.

API Wise Checklist

The below API wise checklist will help the Merchants to handle all the necessary use cases during the integration phase itself to ensure smoother UAT closure.

Note: None of the use cases are Optional. It is mandatory to be implemented.

Quick Links

• Authorization API
• Payment API
• Order Status API
• Webhook Handling
• Refund API
• Refund Status API

Authorization API

• Merchants must rely on the expires_at parameter received in the response.
  
• Option 1: Merchant should check whether the token is active or expired before every API request.
  • If token is active, then the same token can be used in the API request.
  • If token is expired, then the Authorization API should be called to regenerate the new token and use the new token in the API request

• Option 2: Merchant can setup a scheduler that will regenerate the new token by calling Authorization API, 3 or 5 minutes before the actual expiry of the existing token.
  
• Note: Merchant should not call the Authorization API to fetch the new token before every API request without relying on the expiry.

Payment API

Request

• merchantOrderId – Merchants should always pass unique merchantOrderId for each and every request.
• expireAfter – Order expiry in seconds. If not passed, default value will be used. [For Standard Checkout: Min Value = 300, Max Value = 3600 (in Seconds)]
• amount – Merchants should pass the amount parameter value in Paise (Multiply the Rs value by 100)
• udf – Merchants should pass the user defined fields in metaInfo only if it is being used, otherwise skip the metaInfo. Currently 5 fields are provided and use only the number of fields required and remove the fields which are not being used instead of passing empty value.
• paymentFlow.redirectUrl – should be passed with the Merchant’s redirection URL where the UI control will be given back once the payment is completed by the user.
• paymentFlow.type – should be passed PG_CHECKOUT

Response

• orderId – In the Payment API response, PhonePe will provide the orderId parameter which is PhonePe generated OrderId for that transaction. Merchants can map the OrderId received in response with the merchantOrderId passed in the request.
  
• redirectUrl – In the Payment API response of Standard Checkout, the redirectUrl parameter will contain the PhonePe checkout’s URL which the Merchant has to redirect the user on the browser. Merchant must ensure the URL shared by PhonePe is used as it is without modifying or truncating any value in the URL.

Order Status API

• Avoid Strict Deserialization of the response payload.
  
• Merchants must rely on the root level “state” parameter for the payment status confirmation.
  • COMPLETED – The transaction is successful.
  • FAILED – The transaction has failed.
  • PENDING – The transaction is still in the processing state.

Handling Pending Scenario:

• If the state is PENDING, then there can be two possibilities.
  Option 1:  
  • The transaction can be marked as Failed by the merchant and the Payment Failure page can be shown to the users on the UI.
    
  • At the same time, the transaction has to be reconciled on the server side till the terminal status Success/Failure is reached. If successful, then the Refund has to be initiated.
    Note: For this use case, it is highly recommended to integrate the Refund API.
    
• Option 2:
  • The transaction can be marked as Pending by the merchant and the Payment Pending page can be shown to the users on the UI.
    
  • At the same time, the transaction has to be reconciled on the server side till the terminal status COMPLETED/FAILED is reached. If it is successful, then the Order can be fulfilled.

For PENDING, the reconciliation process must be setup, and the recommended frequency interval of PG Order Status API as follows:

Order Status API – Reconciliation [MANDATORY]

If the payment status is Pending, then Order Status API should be called in the following interval:

• The first status check at 20-25 seconds post transaction start, then
  Every 3 seconds once for the next 30 seconds,
  Every 6 seconds once for the next 60 seconds,
  Every 10 seconds for the next 60 seconds,
  Every 30 seconds for the next 60 seconds, and then
  Every 1 min until the terminal state (Else, till the expireAfter value passed in the request).

Webhook Handling

• Avoid Strict Deserialization of the response payload.
  
• Merchants must rely only on the root level “payload.state” parameter for the payment status confirmation.
  
• Don’t rely on “type” parameter in the webhook response (This will be deprecated) instead Merchants must rely on the “event” parameter only for the webhook event name.

• expireAt and timestamp parameters will be a epoch timestamp ( in milliseconds)
  
• [MANDATORY] Once the response is received, Merchants should calculate the Authorization header value (SHA256(username:password)) and match with the value received in the webhook headers.
  • Only if both the values are matching, Merchants should update the payment status.
  • If the values doesn’t match, the webhook can be a fraudulent response and it should be ignored. Further, Merchants can update the realtime status based on Order Status API response.

• Webhook Config:
  • UAT: Share the UAT webhook URL with the Integration team on the integration thread to get it configured for the UAT MID.
    Note: For Production, Merchants should configure directly on the PhonePe Business Dashboard.

Refund API

Note: Refunds can be initiated via Dashboard or API. The below details are applicable only if the Refund is implemented via API.

• merchantRefundId – Merchants should always pass unique merchantRefundId for each and every refund request.
  
• originalMerchantOrderId – Merchants should pass the actual merchantOrderId passed in the Payment API for which the refund has to be done.
  
• amount – Merchants should pass the amount parameter value in Paise (Multiply the Rs value by 100)
  
• Once the Refund is initiated, the initial state will be “PENDING” and Merchants can get the updated status either via Webhook or Refund Status API. It is mandatory to implement both.

Refund Status API

• Avoid Strict Deserialization of the response payload.

• Merchants must rely on the root level “state” parameter for the refund status confirmation.
  
  • If you receive the “state” parameter as PENDING or CONFIRMED in the Refund API response, then the Order Status API with the merchantRefundId should be called for this refund transaction until the final state COMPLETED/FAILED is reached. The Scheduler/Cron Job must be set as per the merchant’s convenience to get the terminal state. Also, Merchants should make sure not to initiate another refund for the same transaction while previous refund transaction is still in the PENDING or CONFIRMED state.
    
  • If you receive the “state” parameter as COMPLETED in the Refund Order Status API response, then the refund has been processed successfully.
    
  • If you receive the “state” parameter as FAILED in the Refund Order Status API response, then the refund transaction has failed and the refund has to be reinitiated again with a unique merchantRefundId.