Contact Us

Pay API

post https://api-preprod.phonepe.com/apis/hermes/pg/v1/pay

This API initiates a payment transaction.

Quick Links

Instrument Type

Link to Refer

Web Flow

Pay Request For Web Flow

Card - New Card

Pay Request For New Card Flow

UPI - Open Intent

Pay Request For UPI Open Intent Flow

Card - With Card Id

Pay Request with Card Id

Card - With Token

Pay Request with Token

UPI - Collect

Pay Request for UPI Collect

UPI - QR

Pay Request for UPI QR

NET BANKING

Pay Request for NET BANKING

👍

The API endpoint remains the same for all the payment instruments.

Request Headers

Header Name

Header Value

Content-Type

application/json

X-VERIFY

SHA256(base64 encoded payload + "/pg/v1/pay" +
salt key) + ### + salt index

Request Parameters - Common Parameters

Parameter Name

Data Type

Description

Mandatory

Comments

merchantId

STRING

Unique MerchantID assigned to the merchant by PhonePe

Yes

merchantTransactionId

STRING

Unique TransactionID generated by the merchant to track request to PhonePe
transactionId length should be less than 38 characters.

Yes

amount

LONG

Transaction amount in Paise

Yes

merchantUserId

STRING

Unique UserID of the users generated by the merchant.

Note:
Avoid passing email/mobile number.

Conditional

Mandatory if paymentInstrument.type is:
● PAY_PAGE
● CARD
● SAVED_CARD
● TOKEN
● NET_BANKING

Optional for if paymentInstrument.type is:
● UPI_INTENT
● UPI_COLLECT
● UPI_QR

redirectUrl

STRING

The url where the user will be redirected after transaction completion.

Yes

redirectMode

ENUM

GET / POST modes for redirectUrl

Yes

Possible values:
● GET
● POST

callbackUrl

STRING

The url where server to server callback will be posted. Always POST

Yes

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.

customerDetails

OBJECT

Customer details

No

productInfo

OBJECT

Product information

No

paymentInstrument

OBJECT

Payment details

Yes

paymentInstrument.type

ENUM

Payment instrument type

Yes

Possible values:
● PAY_PAGE
● CARD
● UPI_INTENT
● SAVED_CARD
● TOKEN
● UPI_COLLECT
● UPI_QR
● NET_BANKING

Pay Request For Web Flow

Sample Request 

{
  "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"
}

Request Field Details
For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

paymentInstrument.type

ENUM

Type of instrument with which payment is being initiated

Yes

Values = PAY_PAGE

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"
      }
    }
  }
}

Pay Request For Card Flow

Sample Request 

{
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "OD620471739210623",
    "merchantUserId": "MU933037302229373",
    "amount": 10000,
    "redirectUrl": "https://webhook.site/redirect-url",
    "redirectMode": "POST",
    "callbackUrl": "https://webhook.site/callback-url",
    "mobileNumber": "9999999999",
    "paymentInstrument": {
        "type": "CARD",
        "authMode": "3DS",
        "saveCard": true,
        "cardDetails": {
            "encryptedCardNumber": "<encrypted_card_number>",
            "encryptionKeyId": 69213,
            "cardHolderName": "Carlos Sainz",
            "expiry": {
                "month":"06",
                "year":"2025"
            },
            "cvv": "420",
            "billingAddress": {
                "line1": "Unit No.001, Ground Floor, Boston House",
                "line2": "Suren Road, Andheri(East)",
                "city": "Mumbai",
                "state": "Maharashtra",
                "zip": "400093",
                "country": "India"
            }
        }
    }
}

{
  "request":"ewogICAgIm1lcmNoYW50SWQiOiAiTUVSQ0hBTlRVQVQiLAogICAgIm1lcmNoYW50VHJhbnNhY3Rpb25JZCI6ICJPRDYyMDQ3MTczOTIxMDYyMyIsCiAgICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICAgImFtb3VudCI6IDEwMDAwLAogICAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgICAgICJ0eXBlIjogIkNBUkQiLAogICAgICAgICJhdXRoTW9kZSI6ICIzRFMiLAogICAgICAgICJzYXZlQ2FyZCI6IHRydWUsCiAgICAgICAgImNhcmREZXRhaWxzIjogewogICAgICAgICAgICAiZW5jcnlwdGVkQ2FyZE51bWJlciI6ICI8ZW5jcnlwdGVkX2NhcmRfbnVtYmVyPiIsCiAgICAgICAgICAgICJlbmNyeXB0aW9uS2V5SWQiOiA2OTIxMywKICAgICAgICAgICAgImNhcmRIb2xkZXJOYW1lIjogIkNhcmxvcyBTYWlueiIsCiAgICAgICAgICAgICJleHBpcnkiOiB7CiAgICAgICAgICAgICAgICAibW9udGgiOiIwNiIsCiAgICAgICAgICAgICAgICAieWVhciI6IjIwMjUiCiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJjdnYiOiAiNDIwIiwKICAgICAgICAgICAgImJpbGxpbmdBZGRyZXNzIjogewogICAgICAgICAgICAgICAgImxpbmUxIjogIlVuaXQgTm8uMDAxLCBHcm91bmQgRmxvb3IsIEJvc3RvbiBIb3VzZSIsCiAgICAgICAgICAgICAgICAibGluZTIiOiAiU3VyZW4gUm9hZCwgQW5kaGVyaShFYXN0KSIsCiAgICAgICAgICAgICAgICAiY2l0eSI6ICJNdW1iYWkiLAogICAgICAgICAgICAgICAgInN0YXRlIjogIk1haGFyYXNodHJhIiwKICAgICAgICAgICAgICAgICJ6aXAiOiAiNDAwMDkzIiwKICAgICAgICAgICAgICAgICJjb3VudHJ5IjogIkluZGlhIgogICAgICAgICAgICB9CiAgICAgICAgfQogICAgfQp9"
}

Request Field Details
For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

paymentInstrument.type

ENUM

Type of instrument with which payment is being initiated

Yes

Values = CARD

authMode

STRING

Authorisation mode with PG for payment validation

Yes

saveCard

BOOLEAN

true if merchant wants to save token on phonepe platform

Yes

encryptionKeyId

LONG

KeyId of key which merchant uses to encrypt card number

Yes

encryptedCardNumber

STRING

Encrypted 16-Digit Card Number entered by the user.
Encryption Method: RSA 4096

Yes

cardHolderName

STRING

Name of holder printed on card

Yes

expiry.month

STRING

Card Expiry Month

Yes

expiry.year

STRING

Card Expiry Year

Yes

cvv

STRING

CVV of the card with which payment is being initiated

Yes

billingAddress

OBJECT

Billing address details to be passed to the PG

No

Sample Response 

{
    "success": true,
    "code": "PAYMENT_INITIATED",
    "message": "Payment initiated",
    "data": {
        "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "MT7850590068188104",
        "transactionId": "T2204071334465821320730",
        "instrumentResponse": {
            "type": "CARD",
            "redirectInfo": {
                "url": "https://pg-uat.phonepe.com/pg-transport/v1/redirect/dummy?id=d085d94a-8d58-4043-a73f-31e9de41af46",
                "method": "GET"
            }
        }
    }
}

Sample S2S Callback after Card Tokenization is Success

{
  "success": true,
  "code": "TOKENIZATION_SUCCESS",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "state": "COMPLETED",
    "responseCode": "TOKENIZATION_SUCCESS",
    "cardId": "C34081038691063664100",
    "cardMetaData": {
      "cardType": "CREDIT_CARD",
      "cardIssuer": "VISA",
      "bankCode": "ICICI",
      "cardSuffix": "5544",
      "expiry": {
        "month": "12",
        "year": "2030"
      }
    },
    "tokenMetaData": {
      "panReferenceNumber": "qzyezl9ocsw42m3tckli",
      "tokenBin": "456234",
      "expiry": {
        "month": "12",
        "year": "2030"
      },
      "tokenState": "ACTIVE"
    }
  }
}

Sample S2S Callback after Card Tokenization is Failed

{
  "success": false,
  "code": "TOKENIZATION_ERROR",
  "message": "Your request has been successfully completed.",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "state": "FAILED",
    "responseCode": "AUTH_TRANSACTION_FAILED"
  }
}

Pay Request For UPI Open Intent Flow

Sample Request 

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MU933037302229373",
  "amount": 10000,
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "deviceContext": {
    "deviceOS": "ANDROID"
  },
  "paymentInstrument": {
    "type": "UPI_INTENT",
    "targetApp": "com.phonepe.app"
  }
}

{
  "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MU933037302229373",
  "amount": 10000,
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "deviceContext": {
    "deviceOS": "IOS"
  },
  "paymentInstrument": {
    "type": "UPI_INTENT",
    "targetApp": "PHONEPE"
  }
}

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKIAkibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJBTkRST0lEIgogIH0sCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0lOVEVOVCIsCiAgICAidGFyZ2V0QXBwIjogImNvbS5waG9uZXBlLmFwcCIKICB9Cn0="
}

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKIAkibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VOTMzMDM3MzAyMjI5MzczIiwKICAiYW1vdW50IjogMTAwMDAsCiAgImNhbGxiYWNrVXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL2NhbGxiYWNrLXVybCIsCiAgIm1vYmlsZU51bWJlciI6ICI5OTk5OTk5OTk5IiwKICAiZGV2aWNlQ29udGV4dCI6IHsKICAgICJkZXZpY2VPUyI6ICJJT1MiCiAgfSwKICAicGF5bWVudEluc3RydW1lbnQiOiB7CiAgICAidHlwZSI6ICJVUElfSU5URU5UIiwKICAgICJ0YXJnZXRBcHAiOiAiUEhPTkVQRSIKICB9Cn0="
}

Request Field Details
For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

paymentInstrument.type

STRING

Type of instrument with which payment is being initiated

Yes

value = UPI_INTENT

paymentInstrument.targetApp

ENUM

Target app for intent.
For iOS: If one needs to generate an intent url targeted at specific app on iOS, then the respective value should be passed.

For ANDROID: If one needs to open specific app on intent, then the respective package name needs to be passed.

Yes

Possible values for iOS:
● PHONEPE
● GPAY
● PAYTM

Possible values for Android:
Android package name
(For example:
● com.phonepe.app for PHONEPE
● net.one97.paytm for PAYTM)

deviceContext.deviceOS

STRING

Device Operating System

ENUM

Possible values for iOS:
● ANDROID
● IOS

Sample Response 

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
        "instrumentResponse": {
            "type": "UPI_INTENT",
            "intentUrl": "upi://[email protected]&pn=MerchantUAT&am=3.00&mam=3.00&tr=OD620471739210623&tn=Payment%20for%OD620471739210623&mc=5311&mode=04&purpose=00&utm_campaign=DEBIT&utm_medium=FKRT&utm_source=OD620471739210623"
    }   
    }
}

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "instrumentResponse": {
      "type": "UPI_INTENT",
      "intentUrl": "ppe://[email protected]&pn=MerchantUAT&am=1.00&mam=1.00&tr=MT7850590068188104&tn=Payment%20for%20MT7850590068188104&mc=5311&mode=04&purpose=00&utm_campaign=B2B_PG&utm_medium=JUSPAYUAT&utm_source=MT7850590068188104"
    }
  }
}

Sample Failure Response 

{
  "success": false,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

Pay Request with Card Id

Sample Request 

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "OD620471739210623",
  "merchantUserId": "MU933037302229373",
  "amount": 10000,
  "redirectUrl": "https://mykewlapp.com/redirect",
  "redirectMode": "POST",
  "callbackUrl": "https://mykewlapp.com/callback",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "SAVED_CARD",
    "authMode": "3DS",
    "cardDetails": {
      "cardId": "C903889349294273423",
      "cvv": "223"
    }
  }
}

{
  "request":"ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVU5MzMwMzczMDIyMjkzNzMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL3JlZGlyZWN0IiwKICAicmVkaXJlY3RNb2RlIjogIlBPU1QiLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiU0FWRURfQ0FSRCIsCiAgICAiYXV0aE1vZGUiOiAiM0RTIiwKICAgICJjYXJkRGV0YWlscyI6IHsKICAgICAgImNhcmRJZCI6ICJDOTAzODg5MzQ5Mjk0MjczNDIzIiwKICAgICAgImN2diI6ICIyMjMiCiAgICB9CiAgfQp9"
}

Request Field Details
For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

paymentInstrument.type

ENUM

Type of instrument with which payment is being initiated

Yes

Values = SAVED_CARD

authMode

STRING

Authorisation mode with PG for payment validation

Yes

value = 3DS

cardId

STRING

CardId for the user as sent by phonepe when the card was saved on phonepe platform

Yes

cvv

STRING

CVV of the card with which payment is being initiated

Yes

Sample Response 

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "MT7850590068188104",
    "transactionId": "OD620471739210623",
    "instrumentResponse": {
        "type": "SAVED_CARD",
            "redirectInfo": {
                "url": "https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224",
                "method": "GET"
            }
    }
  }
}

Pay Request with Token

Sample Request

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "U4909206497168257",
  "amount": 10000,
  "redirectUrl": "https://webhook.site/redirect-url",
  "redirectMode": "POST",
  "callbackUrl": "https://webhook.site/callback-url",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "TOKEN",
    "authMode": "3DS",
    "tokenDetails": {
      "cvv": "739",
      "cryptogram": "95031131582962057737",
      "encryptedToken": "SJk7Sazu894+cHsxsTOLML5ZYseMzdQ",
      "encryptionKeyId": 10,
      "expiry": {
        "month": "11",
        "year": "2037"
      },
      "panSuffix": "1212",
      "cardHolderName": "Prashant"
    }
  }
}

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIlU0OTA5MjA2NDk3MTY4MjU3IiwKICAiYW1vdW50IjogMTAwMDAsCiAgInJlZGlyZWN0VXJsIjogImh0dHBzOi8vd2ViaG9vay5zaXRlL3JlZGlyZWN0LXVybCIsCiAgInJlZGlyZWN0TW9kZSI6ICJQT1NUIiwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlRPS0VOIiwKICAgICJhdXRoTW9kZSI6ICIzRFMiLAogICAgInRva2VuRGV0YWlscyI6IHsKICAgICAgImN2diI6ICI3MzkiLAogICAgICAiY3J5cHRvZ3JhbSI6ICI5NTAzMTEzMTU4Mjk2MjA1NzczNyIsCiAgICAgICJlbmNyeXB0ZWRUb2tlbiI6ICJTSms3U2F6dTg5NCtjSHN4c1RPTE1MNVpZc2VNemRRIiwKICAgICAgImVuY3J5cHRpb25LZXlJZCI6IDEwLAogICAgICAiZXhwaXJ5IjogewogICAgICAgICJtb250aCI6ICIxMSIsCiAgICAgICAgInllYXIiOiAiMjAzNyIKICAgICAgfSwKICAgICAgInBhblN1ZmZpeCI6ICIxMjEyIiwKICAgICAgImNhcmRIb2xkZXJOYW1lIjogIlByYXNoYW50IgogICAgfQogIH0KfQ=="
}

Request Field Details

For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

paymentInstrument.type

ENUM

Type of instrument with which payment is being initiated

Yes

Values = TOKEN

encryptedToken

STRING

Encrypted TOKEN number which merchant passes to process card transaction
Encryption Method: RSA 4096

Yes

encryptionKeyId

LONG

KeyId of key which merchant uses to encrypt token

Yes

expiry.month

STRING

Token expiry month

Yes

expiry.year

STRING

Token expiry year

Yes

cryptogram

STRING

Cryptogram which is generated in the get transaction data call

Yes

panSuffix

STRING

Last four digits of cardNumber

Yes

cardHolderName

STRING

Card Holder Name

No

merchantUserId

STRING

Merchant User Id unique for the customer

No

Sample Response

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "MT7850590068188104",
    "transactionId": "T9693997646897938",
        "instrumentResponse": {
        "type": "TOKEN",
            "redirectInfo": {
                "url": "https://pg.phonepe.com/redirect?id=5dd821c4-4cf1-498e-86de-928901d84224",
                "method": "GET"
            }
        }
  }
}

Pay Request for UPI Collect

Sample Request 

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "OD620471739210623",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "callbackUrl": "https://mykewlapp.com/callback",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "UPI_COLLECT",
    "vpa": "[email protected]"
  }
}

🚧

Test VPA

For testing in the UAT environment, kindly use the VPA of the PhonePe PreProd app only.
To setup VPA, refer Creating/Viewing VPA from here
Example: [email protected]

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk9ENjIwNDcxNzM5MjEwNjIzIiwKICAibWVyY2hhbnRVc2VySWQiOiAiTVVJRDEyMyIsCiAgImFtb3VudCI6IDEwMDAwLAogICJjYWxsYmFja1VybCI6ICJodHRwczovL215a2V3bGFwcC5jb20vY2FsbGJhY2siLAogICJtb2JpbGVOdW1iZXIiOiAiOTk5OTk5OTk5OSIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgInR5cGUiOiAiVVBJX0NPTExFQ1QiLAogICAgInZwYSI6ICJ0ZXN0LXZwYUB5YmwiCiAgfQp9"
}

Request Field Details
For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

type

STRING

Type of instrument with which payment is being initiated

Yes

value = UPI_COLLECT

vpa

STRING

VPA of user initiating payment

Sample Response 

{
    "success": true,
    "code": "PAYMENT_INITIATED",
    "message": "Payment initiated",
    "data": {
        "merchantId": "RUMMYLEGENDSUAT",
        "merchantTransactionId": "d852fe13-a25e-4c49-82e1-27aab36b40e1",
        "instrumentResponse": {
            "type": "UPI_COLLECT"
        }
    }
}

Sample Failure Response 

{
  "success": false,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

🚧

For UPI Collect, VPA have to be verified.

  • In UPI collect flow, users have to enter a Virtual Payment Address (VPA) to make the payment. The VPA can be verified using VPA Validate API.

  • The Collect Request will be valid for 8mins. Merchants can display the timer on the payment processing page to keep the user aware of the time left to complete the payment.

Pay Request for UPI QR

Sample Request 

{
  "merchantId": "MERCHANTUAT",
  "merchantTransactionId": "MT7850590068188104",
  "merchantUserId": "MUID123",
  "amount": 10000,
  "callbackUrl": "https://mykewlapp.com/callback",
  "mobileNumber": "9999999999",
  "paymentInstrument": {
    "type": "UPI_QR"
  }
}

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly9teWtld2xhcHAuY29tL2NhbGxiYWNrIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIlVQSV9RUiIKICB9Cn0="
}

Request Field Details
For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

type

STRING

Type of instrument with which payment is being initiated

Yes

value = UPI_QR

Sample Response 

{
  "success": true,
  "code": "PAYMENT_INITIATED",
  "message": "Payment Initiated",
  "data": {
    "merchantId": "MERCHANTUAT",
    "merchantTransactionId": "OD620471739210623",
    "instrumentResponse": {
      "type": "UPI_QR",
      "qrData": "<Base64 encoded QR image string>",
      "intentUrl": "upi://[email protected]&pn=MERCHANTUAT&am=100.00&mam=100.00&tr=4bf0738a-e686-464f-87f5-b249d1e56c2a&tn=Payment%20for%204bf0738a-e686-464f-87f5-b249d1e56c2a&mc=5311&mode=04&purpose=00&utm_campaign=B2B_PG&utm_medium=JUSPAYUAT&utm_source=4bf0738a-e686-464f-87f5-b249d1e56c2a"
    }
  }
}

🚧

Generating QR Image

In the UPI QR response, either qrData or intentUrl can be converted to the QR Image and shown to the user.

Pay Request for NET BANKING

📘

  • To get the list of NetBanking Banks and it's current availability status, Payment Options API can be used.
  • To fetch the Bank or Default Netbanking Logo, refer here

Sample Request

{
  "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": "NET_BANKING",
        "bankId": "SBIN"
  }
}

{
  "request": "ewogICJtZXJjaGFudElkIjogIk1FUkNIQU5UVUFUIiwKICAibWVyY2hhbnRUcmFuc2FjdGlvbklkIjogIk1UNzg1MDU5MDA2ODE4ODEwNCIsCiAgIm1lcmNoYW50VXNlcklkIjogIk1VSUQxMjMiLAogICJhbW91bnQiOiAxMDAwMCwKICAicmVkaXJlY3RVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvcmVkaXJlY3QtdXJsIiwKCSJyZWRpcmVjdE1vZGUiOiAiUE9TVCIsCgkiY2FsbGJhY2tVcmwiOiAiaHR0cHM6Ly93ZWJob29rLnNpdGUvY2FsbGJhY2stdXJsIiwKICAibW9iaWxlTnVtYmVyIjogIjk5OTk5OTk5OTkiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJ0eXBlIjogIk5FVF9CQU5LSU5HIiwKCQkiYmFua0lkIjogIlNCSU4iCiAgfQp9"
}

Request Field Details

For Common request parameters, refer here

Parameter Name

Data Type

Description

Mandatory

Comments

type

STRING

Type of instrument with which payment is being initiated

Yes

value = NET_BANKING

bankId

STRING

A short code to identify the bank selected by user

Yes

Example value = HDFC
Id’s for all banks can be obtained from the Response of Options API > NetBanking > All banks list.

Sample Response

{
    "success": true,
    "code": "PAYMENT_INITIATED",
    "message": "Payment initiated",
    "data":
    {
        "merchantId": "MERCHANTUAT",
        "merchantTransactionId": "MT7850590068188104",
        "transactionId": "T2208051605137945169863",
        "instrumentResponse":
        {
            "type": "NET_BANKING",
            "redirectInfo":
            {
                "url": "https://pg-uat.phonepe.com/pg-transport/v1/redirect/tib?id=670fac79-1ccc-42b4-b0b5-af36c6b6db09",
                "method": "GET"
            }
        }
    }
}

Response Details

Response Headers

Header Name

Header Value

Content-Type

application/json

Response Parameters

Parameter Name

Data Type

Description

Comments

success

BOOLEAN

Success/failure of request processing

code

STRING

Response code explaining reason for status.

For status SUCCESS, only one possible response code is present

  • PAYMENT_INITIATED
    For status FAILURE, following response codes are possible:
    ● BAD_REQUEST
    ● AUTHORIZATION_FAILED
    ● PAYMENT_ERROR
    ● INTERNAL_SERVER_ERROR

message

STRING

Message giving more information about the code.

merchantId

STRING

Merchant id

merchantTransactionId

STRING

Transaction id generated by merchant

transactionId

STRING

Transaction id generated by PhonePe

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

redirectInfo

STRING

Payload for redirecting user to bank page for authentication

url

STRING

Url on which user needs to be redirected for authentication

method

STRING

http method for loading redirect url

headers

Map<String, String>

Request headers to be passed while loading redirect url

data

Map<String, String>

Form data to be submitted to redirect url page

Error Codes

Code

Description

PAYMENT_INITIATED

Payment is initiated successfully

PAYMENT_ERROR

Payment initiation has failed

INTERNAL_SERVER_ERROR

Something went wrong

BAD_REQUEST

Invalid request

AUTHORIZATION_FAILED

X-VERIFY header is incorrect

Common errors related to X-Verify header

Scenario

Error Code

Response Body

X-Verify is not passed in request headers or passed in different format than expected

400 (Bad Request)

Incorrect X-Verify header passed in request

401

{"success":false,"code":"401"}

Language
Click Try It! to start a request and see the response here!