Cashfree UPI

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

  • API
  • Intent

API

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.
  4. Link: Pay using an UPI scheme link using any UPI app.

Endpoints

URL Environment
https://test.cashfree.com/billpay/checkout/post/submit TEST
https://www.cashfree.com/checkout/post/submit PRODUCTION

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

Parameter Required Description
appId Yes Your app id
secretKey Yes Your Secret Key
orderId Yes Order/Invoice Id
orderAmount Yes Bill amount of the order
orderCurrency No Currency 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
orderNote No A help text to make customers know more about the order
customerName Yes Name of the customer
customerPhone Yes Phone number of customer
customerEmail Yes Email id of the customer
returnUrl Yes Return URL to which user will be redirected after the payment (max-len 500)
notifyUrl No Notification URL for server-server communication. Useful when user’s connection drops while re-directing (max-len 500)
notifyUrl should be an https URL
signature Yes Request signature
paymentOption Yes Value should be “upi”
responseType Yes Value should be “json”
upiMode No The 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</br> 2.’qrcode’ this will provide with qrCode in response</br> 3.’link’ this will provide the upi pay scheme link as response
upi_vpa Yes User vpa for the transaction. Not required for upiMode = ‘gpay’,’qrcode’,’link’. Mandatory for other collect request

Response (Content-Type-application/json)

Parameter Type Description
status String Status of API call “OK”, “ERROR”
orderId String Order/Invoice Id
referenceId String ReferenceId of the UPI transaction
message String Message if any
qr String Base64 png image. This is returned when upiMode ‘qrcode’ is used
link String UPI scheme link that can used to pay using an UPI app returned when upiMode ‘link’is used

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

Parameter Description
orderId Order id for which transaction has been processed. Ex: GZ-212”
orderAmount Amount of the order. Ex: 256.00
referenceId transaction reference id, if payment has been attempted
txStatus transaction status, if a payment has been attempted
paymentMode payment mode of transaction, if payment has been attempted
txMsg transaction message, if payment has been attempted
txTime transaction time, if payment has been attempted
signature response signature

Endpoint to verify the keys

URL Environment
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)

You can find your appId and secret key from the merchant dashboard linked here

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

Parameter Type Description
X-Client-Id String Your app id
X-Client-Secret String Secret Key
Content-Type String application/json

Validate VPA

GET /upi/validate/@vpa

Path Variables

Parameter Type Description
vpa String Upi Vpa of the user

Response

Parameter Type Description
status String Status of API call “OK”, “ERROR”
valid String Vpa validation status- True or False
name String Vpa User Name this can be “NA” in some cases
vpa String Upi 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

Order Status

GET /orders/@orderId/status

Path Variables

Parameter Type Description
orderId String OrderId used for creating the payment

Response

Parameter Description
status Status of API call “OK”, “ERROR”
txStatus transaction status, if a payment has been attempted
txMsg transaction message, if payment has been attempted
txTime transaction time, if payment has been attempted
referenceId transaction time, if payment has been attempted
paymentMode payment mode of transaction, if payment has been attempted
orderCurrency rcurrency of the order
txTime transaction time, if payment has been attempted
paymentDetails.paymentMode payment mode of transaction, if payment has been attempted
paymentDetails.bankName Name of the bank if payment has been attempted (only incase of Netbanking)
paymentDetails.cardNumber Masked card number if payment has been attempted(only in case of Debit & Credit Cards)
paymentDetails.cardCountry Country code of the card if payment has been attempted (only in case of Debit & Credit Cards)
paymentDetails.cardScheme Scheme 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