šŸ‘

URL

PreProd Host URL: https://api-preprod.phonepe.com/apis/merchant-simulator
API End Point: /pg/v1/pay
URL: https://api-preprod.phonepe.com/apis/merchant-simulator/pg/v1/pay

Quick Links

Request Details

Response Details

Request Details

Request Headers

Header NameHeader Value
Content-Typeapplication/json
X-VERIFYSHA256(base64 encoded payload + "/pg/v1/pay" +
salt key) + ### + salt index

Request Parameters

Parameter NameData TypeDescriptionMandatory
merchantIdSTRINGUnique MerchantID assigned to the merchant by PhonePe

Note: merchantId length will be less than 38 characters.
Yes
merchantTransactionIdSTRINGUnique Transaction ID generated by the merchant to track request to PhonePe

Note:
- merchantTransactionId length should be less than 36 characters

- No Special characters allowed except underscore "_"
Yes
amountLONGTransaction amount in PaiseYes
merchantUserIdSTRINGUnique UserID of the users generated by the merchant.

Note:

- merchantUserId length should be less than 36 characters

- Should be alphanumeric only.
Yes
redirectUrlSTRINGThe url where the user will be redirected after transaction completion.Yes
redirectModeENUMredirectMode should be:
ā— POST
Yes
callbackUrlSTRINGThe url where server to server callback will be posted. Always POST.

Note: This callback will be of POST type and will contain the same payload as the status response. The callback will contain an X-VERIFY header which the merchant should verify before decoding the response.
Yes
paymentInstrumentOBJECTPayment detailsYes
paymentInstrument.typeENUMPayment instrument type.
Value will be: PAY_PAGE
Yes
mobileNumberSTRINGMobile number of the userNo

Sample Request for Pay Page

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "redirectUrl": "https://webhook.site/redirect-url",
  "redirectMode": "POST",
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "PAY_PAGE"
  }
}
{
    "request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiUEFZX1BBR0UiCiAgfQp9"
}

How to Calculate X-Verify/Checksum header

šŸ‘

Formula: SHA256(Base64 encoded payload + "/pg/v1/pay" + salt key) + ### + salt index

Base64 encoded payload:
ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiUEFZX1BBR0UiCiAgfQp9

API Endpoint:
/pg/v1/pay

Sample Salt Key:
099eb0cd-02cf-4e2a-8aca-3e6c6aff0399

Sample Salt Index:
1

Final Computation:

SHA256 (ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL3dlYmhvb2suc2l0ZS9jYWxsYmFjay11cmwiLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiUEFZX1BBR0UiCiAgfQp9/pg/v1/pay099eb0cd-02cf-4e2a-8aca-3e6c6aff0399) + ### + 1

Checksum Value :
2cd3a2cd04ff5b453df11e91f97b29fae10fe22522a29c1ae6b7fad41478d8b5###1

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Iniiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "instrumentResponse": {
        "type": "PAY_PAGE",
            "redirectInfo": {
            "url": "https://mercury-uat.phonepe.com/transact?token=MjdkNmQ0NjM2MTk5ZTlmNDcxYjY3NTAxNTY5MDFhZDk2ZjFjMDY0YTRiN2VhMjgzNjIwMjBmNzUwN2JiNTkxOWUwNDVkMTM2YTllOTpkNzNkNmM2NWQ2MWNiZjVhM2MwOWMzODU0ZGEzMDczNA",
        "method": "GET"
      }
    }
  }
}

Response Details

Response Headers

Header NameHeader Value
Content-Typeapplication/json

Response Parameters

Parameter NameData TypeDescription
successBOOLEANSuccess/failure of request processing
codeSTRINGResponse code explaining reason for status- Click here
messageSTRINGMessage giving more information about the code.
merchantIdSTRINGMerchant id
merchantTransactionIdSTRINGTransaction id generated by merchant
transactionIdSTRINGTransaction id generated by PhonePe.
Note: This may not always be available in response of a pay call but will always be available in callback or status call after transaction completion.
redirectInfoSTRINGPayload for redirecting user to bank page for authentication
urlSTRINGUrl on which user needs to be redirected for authentication
methodSTRINGhttp method for loading redirect url
headersMap<String, String>Request headers to be passed while loading redirect url
dataMap<String, String>Form data to be submitted to redirect url page

Response Codes

CodeDescription
PAYMENT_INITIATEDPayment is initiated successfully
PAYMENT_ERRORPayment initiation has failed
INTERNAL_SERVER_ERRORSomething went wrong
BAD_REQUESTInvalid request
AUTHORIZATION_FAILEDX-VERIFY header is incorrect

Common errors related to X-Verify header

ScenarioError CodeResponse Body
X-Verify is not passed in request headers or passed in different format than expected400 (Bad Request)
Incorrect X-Verify header passed in request401{"success":false,"code":"401"}
Language
Click Try It! to start a request and see the response here!