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.
Collect: Send a collect request to a particular user VPA. (Default method)
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.
QR Code: Customer can scan and pay the QR code using any UPI app.
Link: Pay using a UPI scheme link using any UPI app.
Intent: Customers select the UPI app in the device to make the payment. Click here to know more.
URL | Environment |
Test | |
Production |
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. |
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=
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 |
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.
URL | Environment |
Test | |
Production |
Parameter | Type | Description |
| String | Your app id |
| String | Secret Key |
| String | Application/JSON |
Validate customers VPA before initiating the payment to improve the transaction conversion rate.
GET /upi/validate/@vpa
Parameter | Type | Description |
vpa | String | UPI VPA of the user |
Parameter | Type | Description |
| String | Status of API call “OK”, “ERROR” |
| String | VPA validation status- True or False |
| String | VPA User Name this can be “NA” in some cases |
| 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
To check the status of the orders.
GET /orders/@orderId/status
Parameter | Type | Description |
orderId | String | OrderId used for creating the payment |
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
