UPI API

The seamless UPI API flow allows merchants to collect UPI payments. The primary API is used to create a collect request to customers 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. To improve the success rates, Validate VPA API can also be used.

Available UPI Modes

  1. Collect: Send a collect request to a particular user VPA. (Default method)

  2. Google Pay: Send direct notification to google pay for the customers to make the payment. Customers can also enter the phone number to complete the payment. To use this mode, verify your VPA and do a penny test on the Google Pay Dashboard. Google Pay will send the MID to Cashfree. This will enable GPay OMNI channel flow.

  3. QR Code: Customer can scan and pay the QR code using any UPI app.

  4. Link: Pay using a UPI scheme link using any UPI app.

  5. Intent: Customers select the UPI app in the device to make the payment. Click here to know more.

End Points

Request Parameters

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 this parameter is left empty. See the Currency Codes below for a list of available currencies. Write to 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-length is 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

2. ’qrcode’ this will provide with qrCode in response

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 requests.

Response Parameters

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 be used to pay using a 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

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. Click here to view the merchant appId and secret key.

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.

Headers

Parameter

Type

Description

X-Client-Id

String

Your app id

X-Client-Secret

String

Secret Key

Content-Type

String

Application/JSON

Validate VPA

Validate customers VPA before initiating the payment to improve the transaction conversion rate.

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

To check the status of the orders.

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

Currency 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