Partner Checklist (Standard)

UAT Sign-Off Process

Once integration is complete, Partners must share their UAT instance for end-to-end flow verification.
All issues identified during UAT must be fixed and verified by the Partner’s integration POC in the UAT environment itself.

✅ Sign-Off Criteria:

• All mandatory use cases must be successfully validated.
• The integration POC will provide UAT Sign-Off only after complete verification.
• The Partner must acknowledge the sign-off to receive Production credentials.

API Wise Checklist

The following checklist ensures all required scenarios are validated during integration for smooth UAT closure:

Authorization API

• The expires_at parameter in the response should be used to determine token validity.
• Option 1:
  • Check whether the token is active or expired before every API request.
  • If active, the same token can be reused.
  • If expired, call the Authorization API to regenerate a new token and use it.
• Option 2:
  • Set up a scheduler to regenerate a new token by calling the Authorization API 3 to 5 minutes before expiry of the existing token.

Payment API

Request Parameters

• merchantOrderId → Always pass a unique value for every request.
• expireAfter → Defines order expiry in seconds. If not passed, the default value is used.
  • Standard Checkout → Minimum = 300, Maximum = 3600 seconds
• amount → Must be passed in paise (multiply the rupee value by 100).
• udf → User-defined fields can be added inside metaInfo only if required.
  • Maximum of 5 fields are available.
  • Use only the required fields and remove unused fields instead of passing empty values.
• paymentFlow.redirectUrl → The redirection URL where the customer is redirected after completing the payment.
• paymentFlow.type → Value should be PG_CHECKOUT.

Response Parameters

• orderId → PhonePe-generated Order ID for the transaction. This should be mapped with the merchantOrderId passed in the request.
• redirectUrl → For Standard Checkout, this field contains the PhonePe Checkout URL. The response URL must be used exactly as provided without any modification or truncation.

Order Status API

• Avoid strict deserialization of the response payload.
• Always rely on the root-level state parameter for payment status confirmation.

Possible Values of state:

• COMPLETED → Transaction is successful.
• FAILED → Transaction has failed.
• PENDING → Transaction is still in progress.

Handling Pending Transactions

When the status is PENDING, two approaches are possible:

• Option 1:
  • Mark the transaction as Failed on the UI and show the payment failure page.
  • Continue reconciliation on the server side until the status changes to COMPLETED or FAILED.
  • If marked as successful later, trigger a refund.
  • Note: For this flow, integration of the Refund API is strongly recommended.

• Option 2:
  • Mark the transaction as Pending on the UI and show a pending status page to the customer.
  • Continue reconciliation on the server side until the status changes to COMPLETED or FAILED.
  • If marked as successful, proceed to fulfill the order.

Mandatory Reconciliation with Order Status API

For PENDING payments, reconciliation must be performed at the following intervals:

• First check: 20–25 seconds after transaction initiation
• Every 3 seconds for the next 30 seconds
• Every 6 seconds for the next 60 seconds
• Every 10 seconds for the next 60 seconds
• Every 30 seconds for the next 60 seconds
• Every 1 minute until a terminal status is received (or until the expireAfter value is reached)

Webhook Handling

• Avoid strict deserialization of the response payload.
• Rely only on the root-level payload.state parameter for payment status confirmation.
• Do not rely on the type parameter (deprecated). Use the event parameter for webhook event identification.
• expireAt and timestamp values are sent as epoch timestamps (in milliseconds).
• [MANDATORY] Once a webhook response is received, calculate the Authorization header value (SHA256(username:password)) and match it with the value provided in the webhook headers.
  • If the values match, update the payment status.
  • If the values do not match, treat the webhook as fraudulent and ignore it. Payment status can still be updated using the Order Status API.

Webhook APIs

• Only Partner-level Webhooks are supported, not Merchant-level.
• Webhook configuration requires:
  • Webhook URL
  • Username (self-created)
  • Password (self-created)
  • List of webhook events
• Ensure duplicate webhook configurations are not created.
• APIs are available to List, Update, and Delete webhook configurations and should be used as per requirement.

Refund API

• merchantRefundId must be unique for every refund request.
• originalMerchantOrderId should match the merchantOrderId from the Payment API.
• amount must be passed in Paise (₹ value × 100).
• On initiation, refund status will be PENDING. The updated status can be fetched through Webhook or Refund Status API (both are mandatory to implement).

Refund Status API

• Avoid strict deserialization of the response payload.
• Rely on the root-level state parameter for refund status confirmation.

State Handling:

• PENDING / CONFIRMED → Continue reconciliation by calling the Refund Order Status API with merchantRefundId until the status changes to COMPLETED or FAILED.
  • A scheduler/cron job should be configured to fetch terminal status.
  • Do not initiate another refund while a refund is still in PENDING or CONFIRMED state.
• COMPLETED → Refund has been processed successfully.
• FAILED → Refund has failed and should be reinitiated with a new unique merchantRefundId.

TSP Headers

Prerequisites

• Web → Each end merchant must have a unique domain name.
  • Example:
    • Merchant A → https://abc.test.com
    • Merchant B → https://def.test.com
• Android/iOS → Each end merchant must have their own mobile app with unique package/bundle identifiers.

Payment API – Common Headers

• Authorization → Generated using Partner Credentials
• X-MERCHANT-ID → Merchant ID provided by PhonePe (unique per merchant)
• X-SOURCE → Value must be API
• X-SOURCE-PLATFORM → TSP Name (shared by Integration Team)
• X-SOURCE-CHANNEL → Platform where transaction originates (web / android / ios)
• X-MERCHANT-IP → IP address of the end merchant initiating the request

Additional Headers – Web

• X-BROWSER-FINGERPRINT → Dynamically generated from the browser initiating the transaction
• USER-AGENT → Dynamically captured from the browser
• X-MERCHANT-DOMAIN → Domain of the merchant website
• X-SOURCE-REDIRECTION-TYPE → Standard Checkout redirection type
  • PARTNER_REDIRECTION → Redirected via Partner checkout page
  • MERCHANT_REDIRECTION → Redirected directly from Merchant website

Additional Headers – Android

• X-SOURCE-CHANNEL-VERSION → Android OS version
• X-MERCHANT-APP-ID → Merchant App package name

Additional Headers – iOS

• X-SOURCE-CHANNEL-VERSION → iOS version
• X-MERCHANT-APP-ID → Merchant App bundle ID

Other APIs

• Authorization and X-MERCHANT-ID are mandatory headers for:
  • Order Status API
  • Refund API
  • Refund Status API
• For Webhook APIs, only the Authorization header is required.