UPI APIs

UPI API v1.0 Reference

UPI Solution

Introduction

Paysharp APIs are organized around REST. Our API has predictable resource-oriented URLs, accepts JSON requests and returns JSON response, and uses standard HTTP response codes, authentication, and verbs.

You can use our APIs in the sandbox(testing) and production(live) environments. We provide two different API urls and tokens for sandbox and production(live).

Pass API token and content-type for all the requests in header, API token can be generated from merchant dashboard.

  • content-type: application/json
  • authorization: Bearer <Token>

Intent Url API

Create an intent url for an order. Intent URL can be used in mobile websites, by clicking the intent url, the customer can pay using any UPI app available in his mobile phone.

  • URL: /order/intent
  • Method: POST

Request

Parameters Range Datatype Required Description
orderId Max 36 string Y Unique identifier to identify order
amount Min 1 - Max 1 Lac / 5 Lac number Y Amount for the order (Maximum amout range vary based on MCC code)
customerId Max 36 string Y Unique identifier to identify customer
customerName Max 100 string N Customer name
customerMobileNo Max 10 string Y Customer Mobile No.
customerEmail Max 100 string N Customer email address
remarks Max 35 string Y Remark for the transaction. Recommend to pass orderId / invoiceId

Response

Parameters Datatype Description
paysharpReferenceNo string Payment reference number for the payment
intentUrl string Intent Url generated for the orderId
phonepeUrl string Phonepe intent Url is used to open PhonePe app
gpayUrl string Google intent Url is used to open GPay app
orderId string Returns the request value
amount number Returns the request value
customerId string Returns the request value
customerName string Returns the request value
customerMobileNo string Returns the request value
customerEmail string Returns the request value
remarks string Returns the request value

Example

Request

{

   "orderId" :   "APR8910005",

   "amount" :   500,

   "customerId" :   "C_1112",

   "customerName" :   "Ram",

   "customerMobileNo" :   "9111100000",

   "customerEmail" :   "",

   "remarks" :   "Invoice No - APR8910005"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"paysharpReferenceNo" :   "upi_dedc619auJz3YB096Se7Zh",

"intentUrl" :   "upi://pay?...",

"phonepeUrl" :   "phonepe://pay?...",

"gpayUrl" :   "tez://upi/pay?...",

"orderId" :   "APR8910005",

"amount" :   500,

"customerId" :   "C_1112",

"customerName" :   "Ram",

"customerMobileNo" :   "9111100000",

"customerEmail" :   "",

"remarks" :   "Invoice No - APR8910005"

}

}

Dynamic QR Code API

Create a dynamic QR code for an order. The QR code can be scanned and payable from any UPI app, the customer only able to pay the requested amount for the requested order.

  • URL: /order/qrcode
  • Method: POST

Request

Parameters Range Datatype Required Description
orderId Max 36 string Y Unique identifier to identify order
amount Min 1 - Max 1 Lac / 5 Lac number Y Amount for the order (Maximum amout range vary based on MCC code)
customerId Max 36 string Y Unique identifier to identify customer
customerName Max 100 string N Customer name
customerMobileNo Max 10 string Y Customer Mobile No.
customerEmail Max 100 string N Customer email address
remarks Max 35 string Y Remark for the transaction. Recommend to pass orderId / invoiceId

Response

Parameters Datatype Description
paysharpReferenceNo string Payment reference number for the payment
qrCode string Base64 string version of dynamic QR code for the order.
orderId string Returns the request value
amount number Returns the request value
customerId string Returns the request value
customerName string Returns the request value
customerMobileNo string Returns the request value
customerEmail string Returns the request value
remarks string Returns the request value

Example

Request

{

   "orderId" :   "APR8910005",

   "amount" :   500,

   "customerId" :   "C_1112",

   "customerName" :   "Ram",

   "customerMobileNo" :   "9111100000",

   "customerEmail" :   "",

   "remarks" :   "Invoice No - APR8910005"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"paysharpReferenceNo" :   "upi_dedc619auJz3YB096Se7Zh",

"qrCode" :   "data:image/png;base64,/9j/4...",

"orderId" :   "APR8910005",

"amount" :   500,

"customerId" :   "C_1112",

"customerName" :   "Ram",

"customerMobileNo" :   "9111100000",

"customerEmail" :   "",

"remarks" :   "Invoice No - APR8910005"

}

}

Collection Request API

By calling the API, able to send payment collection request to the customerVPA (customer UPI handle) for the order. The customer receives a payment request in the UPI app, the customer can either pay or reject the payment request.

  • URL: /order/request
  • Method: POST

Request

Parameters Range Datatype Required Description
orderId Max 36 string Y Unique identifier to identify order
amount Min 1 - Max 1 Lac / 5 Lac number Y Amount for the order (Maximum amout range vary based on MCC code)
customerVPA Max 255 string Y Customer VPA (UPI handle)
customerId Max 36 string Y Unique identifier to identify customer
customerName Max 100 string N Customer name
customerMobileNo Max 10 string Y Customer Mobile No.
customerEmail Max 100 string N Customer email address
remarks Max 35 string Y Remark for the transaction. Recommend to pass orderId / invoiceId

Response

Parameters Datatype Description
paysharpReferenceNo string Payment reference number for the payment
orderId string Returns the request value
amount number Returns the request value
customerVPA string Returns the request value
customerId string Returns the request value
customerName string Returns the request value
customerMobileNo string Returns the request value
customerEmail string Returns the request value
remarks string Returns the request value

Example

Request

{

   "orderId" :   "APR8910005",

   "amount" :   500,

   "customerVPA" :   "customervpaname@yesb",

   "customerId" :   "C_1112",

   "customerName" :   "Ram",

   "customerMobileNo" :   "9111100000",

   "customerEmail" :   "",

   "remarks" :   "Invoice No - APR8910005"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"paysharpReferenceNo" :   "upi_dedc619auJz3YB096Se7Zh",

"orderId" :   "APR8910005",

"amount" :   500,

"customerVPA" :   "customervpaname@yesb",

"customerId" :   "C_1112",

"customerName" :   "Ram",

"customerMobileNo" :   "9111100000",

"customerEmail" :   "",

"remarks" :   "Invoice No - APR8910005"

}

}

Order Status API

By calling the API, able to get the order status and know the order is success, failed, etc..

  • URL: /order/{orderId}
  • Method: GET

Request

Parameters Range Datatype Required Description
orderId Max 36 string Y Unique identifier to identify order

Response and Example

Refer webhook, Same as webhook except attemptCount parameter

Response Body Sent by Paysharp for Success Case

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

   "orderId" :   "202001051004",

   "customerId" :   "C_1112",

   "customerVPA" :   "pstest5@yesb",

   "amount" :   500,

   "fee" :   5,

   "tax" :   0.90,

   "totalFee" :   5.90,

   "netAmount" :   494.10,

   "paysharpReferenceNo" :   "upi_dedc619auJz3YB096Se7Zh",

   "utrNumber" :   "228200422398",

   "transactionDate" :   "2021-02-20T22:23:20Z",

   "status" :   "SUCCESS",

   "remarks" :   "Invoice No - 202001051004"

   }

}

Response Body Sent by Paysharp for Pending Case

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"orderId" :   "202001051005",

"customerId" :   "0001",

"amount" :   50,

"paysharpReferenceNo" :   "upi_afa3ef251C7Qbtj8Lr900N",

"status" :   "PENDING",

"remarks" :   "Invoice No - 202001051005"

}

}

Response Body Sent by Paysharp for On Progress Case

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"orderId" :   "202001051005",

"customerId" :   "0001",

"amount" :   50,

"paysharpReferenceNo" :   "upi_afa3ef251C7Qbtj8Lr900N",

"status" :   "ON PROGRESS",

"remarks" :   "Invoice No - 202001051005"

}

}

Response Body Sent by Paysharp for Failed Case

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"orderId" :   "202001051009",

"customerId" :   "C_1112",

"customerVPA" :   "pstest5@yesb",

"amount" :   1,

"paysharpReferenceNo" :   "upi_5c2ddc77LLAVf8MhM9bFCS",

"transactionDate" :   "2022-04-05T16:10:39.959Z",

"status" :   "FAILED",

"remarks" :   "Invoice No - 202001051009",

"failureCode" :   "EC00100U69",

"failureReason" :   "Collect Expired"

}

}

Response Body Sent by Paysharp for Timeout Case

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"orderId" :   "202001051008",

"customerId" :   "371944",

"customerVPA" :   "pstest5@yesb",

"amount" :   2000,

"paysharpReferenceNo" :   "upi_c4554747WXdK4e6Jqbj9PW",

"transactionDate" :   "2022-04-08T06:47:05.851Z",

"status" :   "TIMEOUT",

"remarks" :   "Invoice No - 202001051008"

}

}

Response Body Sent by Paysharp for Expired Case

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"orderId" :   "202001051007",

"customerId" :   "customer1",

"amount" :   50,

"paysharpReferenceNo" :   "upi_6e7662d2pA9bg149Wy0Xgb",

"transactionDate" :   null,

"status" :   "EXPIRED",

"remarks" :   "Invoice No - 202001051007"

}

}

Validate VPA API

By calling the API, you are able to verify customerVPA exists and also get the name associated with the VPA.

  • URL: /vpa/validate
  • Method: POST

Request

Parameters Range Datatype Required Description
customerVPA Max 255 string Y Customer VPA (UPI handle)

Note: In the sandbox environment all the VPAs will return false except the following VPAs.

pstest2@yesb

pstest4@yesb

pstest6@yesb

pstest7@yesb

pstest8@yesb

pstest9@yesb

Use the above VPAs for testing to get true

Response

Parameters Datatype Description
isValid boolean Returns true if VPA is valid or not
customerVPA string Returns the request value
customerName string Returns the name associated with VPA otherwise returns empty

Example 1

Request

{

   "customerVPA" :   "pstest2@ybl"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"isValid" :   true,

"customerVPA" :   "pstest2@ybl",

"customerName" :   "Ram"

}

}

Example 2

Request

{

   "customerVPA" :   "pstest00000@yesb"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"isValid" :   false,

"customerVPA" :   "pstest00000@yesb",

"customerName" :   ""

}

}

UPI Webhook

Our system will call your webhook url and post the payment status when payment is received. In case your webhook does not respond, our system marks the call as failed. Your webhook should respond in JSON format with content-type: application/json.

Payment Success Case

Parameters Datatype Description
orderId string Returns the order Id
customerId string Returns the customer Id for the order
customerVPA string Returns the customerVPA for the order (Only returned for collect request API)
amount number Amount for the order
fee number Fee for the transaction
tax number Tax for the transaction fee
totalFee number Sum of fee and tax
netAmount number Actual amount after deducting fee and tax.
paysharpReferenceNo string Payment reference number for the transaction
utrNumber string Unique transaction number provided by Bank
transactionDate datetime Transaction date
status string Status should be SUCCESS
remarks string Remark for the transaction provided by the merchant on create order.
attemptCount number Number of times the webhook invoked(Only returned for webhook response)

Payment Non Success Case

Parameters Datatype Description
orderId string
customerId string
customerVPA string Returns the customerVPA for the order (Only returned for collect request API)
amount number For non-success case always returns as 0
paysharpReferenceNo string
status string

ON PROGRESS

FAILED

TIMEOUT

PENDING

EXPIRED
attemptCount number Number of times the webhook invoked(Only returned for webhook response)
failureCode string Failure code returned by bank
failureReason string Failure reason(description) returned by bank

Response Body Sent by Paysharp for Success Case

    {  

"orderId" :   "202001051004",

"customerId" :   "C_1112",

"customerVPA" :   "pstest5@yesb",

"amount" :   500,

"fee" :   5,

"tax" :   0.90,

"totalFee" :   5.90,

"netAmount" :   494.10,

"paysharpReferenceNo" :   "upi_dedc619auJz3YB096Se7Zh",

"utrNumber" :   "228200422398",

"transactionDate" :   "2021-02-20T22:23:20Z",

"status" :   "SUCCESS",

"remarks" :   "Invoice No - APR8910005",

 "attemptCount" : 1

   }

Response Body Sent by Paysharp for Non Success Case

    {  

"orderId" :   "202001051004",

"customerId" :   "C_1112",

"customerVPA" :   "pstest5@yesb",

"amount" :   0,

"paysharpReferenceNo" :   "upi_dedc619auJz3YB096Se7Zh",

"status" :   "FAILED",

"remarks" :   "Invoice No - 202001051004",

 "attemptCount" : 1,

 "failureCode" : "EC00100NA",

 "failureReason" : "Transaction fail: Invalid MPIN"

   }

Expected Acknowledgement from merchant webhook

Response status

Http Status: 200

Response Body

     {

      "code" :   200,

      "message" :   "success"

    }

API Success and Error Messages

Http Status Code: 200 - Success

400 - Error

Sample Error Response

     {

      "code" :   400,

      "errorCode" :   6001,

      "message" :   "Unable to create order, order exits with the same orderId"

    }

Possible Errors

Error Codes Error Messages
6001 Unable to create order, order exits with the same orderId
6002 order not found
6003 Unable to send collection request, Invalid customerVPA
6004 Amount should be minimum
6500 Bank server not available

Postman Collection

Login to your Sandbox / Production environment and UPI API Postman Collection download from the dashboard.