This guide documents how to use the Cashfree UPI in the below modes.

  • API
  • Intent

The seamless UPI API flow allows merchants to collect UPI payments. The primary API is used to create a collect request to customer’s phone. Once the payment is confirmed a callback will be sent to the notifyUrl. As an alternate Order Status API also can be used to poll the status of the order. As well as to improve success rates, Validate VPA API can also be used(Refer Rest API docs)

Available UPI Modes

  1. Collect: Send a collect request to a particular user vpa.(DEFAULT)
  2. Google Pay: Send direct notification to google pay for the customer to pay.
  3. QR Code: Customer can scan and pay the qr code using any UPI app.
URLEnvironment
https://test.cashfree.com/billpay/checkout/post/submitTEST
https://www.cashfree.com/checkout/post/submitPRODUCTION

Request Parameters(Content-Type-multipart/form-data)

ParameterRequiredDescription
appIdYesYour app id
secretKeyYesYour Secret Key
orderIdYesOrder/Invoice Id
orderAmountYesBill amount of the order
orderCurrencyNoCurrency for the order. INR if left empty. See the Currency Codes below for a list of available currencies. Please contact care@cashfree.com to enable new currencies
orderNoteNoA help text to make customers know more about the order
customerNameYesName of the customer
customerPhoneYesPhone number of customer
customerEmailYesEmail id of the customer
returnUrlYesReturn URL to which user will be redirected after the payment (max-len 500)
notifyUrlNoNotification URL for server-server communication. Useful when user’s connection drops while re-directing (max-len 500)
notifyUrl should be an https URL
signatureYesRequest signature
paymentOptionYesValue should be "upi"
responseTypeYesValue should be "json"
upiModeNoThe mode of UPI request that is being used. By default a collect request is raised. Optional Values are as follows - 1.‘gpay’(Google Pay) which will use customerPhone instead of upi_vpa parameter to send notification directly to Google Pay app
2.’qrcode’ this will provide with qrCode in response
3.’link’ this will provide the upi pay scheme link as response
upi_vpaYesUser vpa for the transaction. Not required for upiMode = ‘gpay’,’qrcode’,’link’. Mandatory for other collect request

Response (Content-Type-application/json)

ParameterTypeDescription
statusStringStatus of API call “OK”, “ERROR”
orderIdStringOrder/Invoice Id
referenceIdStringReferenceId of the UPI transaction
messageStringMessage if any
qrStringBase64 png image. This is returned when upiMode ‘qrcode’ is used
linkString

Example

curl -X POST \
https://test.cashfree.com/billpay/checkout/post/submit \
-H 'Cache-Control: no-cache' \
-H 'content-type: multipart/form-data' \
-F appId=test \
-F orderId=A001 \
-F orderAmount=1 \
-F customerName=Test \
-F customerPhone=9895270649 \
-F customerEmail=test@gmail.com \
-F returnUrl= \
-F notifyUrl=https://test.cashfree.com/notify.php \
-F responseType=json \
-F paymentOption=upi \
-F upi_vpa=testsuccess@gocash \
-F signature=0LqbexARvzFuKfMg0I6GoUunr7239G5gZdZZGAXNMXA=

Callback Response

ParameterDescription
orderIdOrder id for which transaction has been processed. Ex: GZ-212”
orderAmountAmount of the order. Ex: 256.00
referenceIdtransaction reference id, if payment has been attempted
txStatustransaction status, if a payment has been attempted
paymentModepayment mode of transaction, if payment has been attempted
txMsgtransaction message, if payment has been attempted
txTimetransaction time, if payment has been attempted
signatureresponse signature
URLEnvironment
https://test.cashfree.com/api/v2/TEST
https://api.cashfree.com/api/v2/PRODUCTION

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to retrieve your AppId and SecretKey (API keys)

CashFree expects API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials first (check Rest API docs).

Headers

ParameterTypeDescription
X-Client-IdStringYour app id
X-Client-SecretStringSecret Key
Content-TypeStringapplication/json

GET /upi/validate/@vpa

Path Variables

ParameterTypeDescription
vpaStringUpi Vpa of the user

Response

ParameterTypeDescription
statusStringStatus of API call “OK”, “ERROR”
validStringVpa validation status- True or False
nameStringVpa User Name this can be “NA” in some cases
vpaStringUpi Vpa of the user

Example

curl -X GET \
http://test.cashfree.com/api/v2/upi/validate/testsucces@gocash \
-H 'Cache-Control: no-cache' \
-H 'X-Client-Id: Test \
-H 'X-Client-Secret: Test

GET /orders/@orderId/status

Path Variables

ParameterTypeDescription
orderIdStringOrderId used for creating the payment

Response

ParameterDescription
statusStatus of API call “OK”, “ERROR”
txStatustransaction status, if a payment has been attempted
txMsgtransaction message, if payment has been attempted
txTimetransaction time, if payment has been attempted
referenceIdtransaction time, if payment has been attempted
paymentModepayment mode of transaction, if payment has been attempted
orderCurrencyrcurrency of the order
txTimetransaction time, if payment has been attempted
paymentDetails.paymentModepayment mode of transaction, if payment has been attempted
paymentDetails.bankName Name of the bank if payment has been attempted (only incase of Netbanking)
paymentDetails.cardNumberMasked card number if payment has been attempted(only in case of Debit & Credit Cards)
paymentDetails.cardCountryCountry code of the card if payment has been attempted (only in case of Debit & Credit Cards)
paymentDetails.cardSchemeScheme of the card (eg:VISA) if payment has been attempted (only in case of Debit & Credit Cards)
paymentDetails.utr UTR of UPI transaction(only in case of UPI)

Example

curl -X GET \
http://test.cashfree.com/api/v2/orders/1540568899/status \
-H 'Cache-Control: no-cache' \
-H 'X-Client-Id: Test \
-H 'X-Client-Secret: Test

© 2019 Cashfree Payments India Pvt Ltd