UPI Refund APIs

Refund API Refund History API Refund Status API Refund Webhook API Success and Error Messages Postman Collection

UPI Refund API Reference (v1.0)

Limited Preview - Right now Refund API is on invite only basis, Click here to join the waiting list

Introduction

Paysharp APIs are built using REST architecture, featuring predictable, resource-oriented URLs. Our APIs accept JSON-formatted requests, return JSON responses, and utilize standard HTTP verbs, response codes, and authentication methods.

You can integrate Paysharp APIs in both sandbox (testing) and production (live) environments. Separate base URLs and API tokens are provided for each environment.

For every API request, include the following headers:

content-type: application/json
authorization: Bearer <token>

API tokens can be generated from your merchant dashboard.

Refund API

This API allows you to initiate a full or partial refund for any successful UPI transaction.

The original UPI transaction status must be success.
Refunds are only available within 90 days of the transaction date.

URL: /refunds
Method: POST

Request

Parameters	Range	Datatype	Required	Description
paysharpReferenceNo	Max 50	string	Y	Paysharp Reference number of the original UPI transaction.
refundType	Max 7	string	Y	Allowed values: FULL - Full refund PARTIAL - Partial refund
refundAmount	Min 1 - Max within original UPI transaction amount	number	N	Represents the refund amount, applicable only for partial refunds.

Response

Parameters	Datatype	Description
paysharpReferenceNo	string	Returns the request value
refundType	string	Returns the request value
refundAmount	number	Returns the request value
refundPaysharpReferenceNo	string	Returns the unique reference number generated for this refund transaction

Example 1 - Full Refund Case

Request

{

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Zh",

"refundType" : "FULL"

}

Response

{

"code" : 200,

"message" : "success",

"data" : {

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Zh",

"refundType" : "FULL",

"refundAmount" : 500,

"refundPaysharpReferenceNo" : "REFUND189b392bl9VMW3uC4a8eNX"

}

Example 2 - Partial Refund Case

Request

{

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Rn",

"refundType" : "PARTIAL",

"refundAmount" : 200

}

Response

{

"code" : 200,

"message" : "success",

"data" : {

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Rn",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"refundPaysharpReferenceNo" : "REFUND190c392bl9VMW3uC4a8eNW"

}

Refund History API

This API retrieves the complete refund history for a UPI transaction using the reference number "paysharpReferenceNo".

URL: /refunds/{paysharpReferenceNo}
Method: GET

Request

Parameters	Range	Datatype	Required	Description
paysharpReferenceNo	Max 50	string	Y	Reference number for the original UPI transaction.

Response

Parameters	Datatype	Description
orderId	string	Returns the order Id of the original UPI transaction.
customerId	string	Returns the customer Id of the original UPI transaction.
paysharpReferenceNo	string	Paysharp reference number for the original UPI transaction.
originalTransactionAmount	number	Returns the amount received/credited for the UPI transaction.
refundPaysharpReferenceNo	string	Reference number generated for the refund transaction.
refundType	string	Allowed values: FULL - Full refund PARTIAL - Partial refund
refundAmount	number	Amount refunded to the customer for the order.
fee	number	Refund transaction fee.
tax	number	Tax applied to the refund transaction.
totalFee	number	Sum of fee and tax.
refundUtrNumber	string	Unique Transaction Reference (UTR) number provided by the bank for the refund transaction. The refundUtrNumber parameter is returned only when the refund status is "Success" or "Failure".
refundDate	datetime	Refund date in ISO 8601 format. The refundDate parameter is returned only when the refund status is "Success" or "Failure".
mode	string	Always returns "UPI".
status	string	Status of the refund: PENDING - The refund request is in progress and awaiting the final status update SUCCESS - Refund completed successfully FAILURE - Refund failed
isRecredited	Boolean	Indicates whether the refund amount was credited back to the account balance in case of a failed refund.

Example 1 - Full Refund Case

Response

{

"code" : 200,

"message" : "success",

"data" : {

"orderId" : "202001051004",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Zh",

"originalTransactionAmount" : 500,

"refunds" : [

{

"refundPaysharpReferenceNo" : "REFUND189b392bl9VMW3uC4a8eNX",

"refundType" : "FULL",

"refundAmount" : 500,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "228200422398",

"refundDate" : "2025-02-20T11:25:51+05:30",

"mode" : "UPI",

"status" : "SUCCESS"

}

]

}

Example 2 - Partial Refund Case with multiple refunds

Response

{

"code" : 200,

"message" : "success",

"data" : {

"orderId" : "202001051005",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Rn",

"originalTransactionAmount" : 500,

"refunds" : [

{

"refundPaysharpReferenceNo" : "REFUND190c392bl9VMW3uC4a8eNW",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "238200422359",

"refundDate" : "2025-04-19T11:25:51+05:30",

"mode" : "UPI",

"status" : "SUCCESS"

{

"refundPaysharpReferenceNo" : "REFUND190c392bl9VMW3uC4a8eyt",

"refundType" : "PARTIAL",

"refundAmount" : 100,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "228200422357",

"refundDate" : "2025-02-21T11:25:51+05:30",

"mode" : "UPI",

"status" : "SUCCESS"

}

]

}

Example 3 - Partial Refund Case with Success and Failure

Response

{

"code" : 200,

"message" : "success",

"data" : {

"orderId" : "202001051006",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_cekc619auJz3YB096SeH54",

"originalTransactionAmount" : 500,

"refunds" : [

{

"refundPaysharpReferenceNo" : "REFUND199c392bl9VMW3uC4a8eAB",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "238200422355",

"refundDate" : "2025-04-17T12:15:51+05:30",

"mode" : "UPI",

"status" : "FAILURE",

"isRecredited" : true

{

"refundPaysharpReferenceNo" : "REFUND190c392bl9VMW3uC4a8ecd",

"refundType" : "PARTIAL",

"refundAmount" : 100,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "228200422366",

"refundDate" : "2025-02-22T12:35:51+05:30",

"mode" : "UPI",

"status" : "SUCCESS"

}

]

}

Refund Status API

This API provides the status of a specific refund transaction using the refund reference number “refundPaysharpReferenceNo”.

It does not return the full refund history.
You must pass both the UPI transaction reference number and the refund transaction reference number in the API URL path.

URL: /refunds/{paysharpReferenceNo}/{refundPaysharpReferenceNo}
Method: GET

Request

Parameters	Range	Datatype	Required	Description
paysharpReferenceNo	Max 50	string	Y	Reference number for the original UPI transaction.
refundPaysharpReferenceNo	Max 50	string	Y	Reference number for the refund transaction.

Response

Parameters	Datatype	Description
orderId	string	Returns the order Id of the original UPI transaction.
customerId	string	Returns the customer Id of the original UPI transaction.
paysharpReferenceNo	string	Paysharp reference number for the original UPI transaction.
refundPaysharpReferenceNo	string	Reference number generated for the refund transaction.
refundType	string	Allowed values: FULL - Full refund PARTIAL - Partial refund
refundAmount	number	Amount refunded to the customer for the order.
fee	number	Refund transaction fee.
tax	number	Tax applied to the refund transaction.
totalFee	number	Sum of fee and tax.
refundUtrNumber	string	Unique Transaction Reference (UTR) number provided by the bank for the refund transaction. The refundUtrNumber parameter is returned only when the refund status is "Success" or "Failure".
refundDate	datetime	Refund date in ISO 8601 format. The refundDate parameter is returned only when the refund status is "Success" or "Failure".
mode	string	Always returns "UPI".
status	string	Status of the refund: PENDING - The refund request is in progress and awaiting the final status update SUCCESS - Refund completed successfully FAILURE - Refund failed
isRecredited	Boolean	Indicates whether the refund amount was credited back to the account balance in case of a failed refund.

Example

Response Body Sent by Paysharp for Success Case

{

"code" : 200,

"message" : "success",

"data" : {

"orderId" : "202001051005",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Rn",

"refundPaysharpReferenceNo" : "REFUND190c392bl9VMW3uC4a8eNW",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "238200422359",

"refundDate" : "2025-04-19T11:25:51+05:30",

"mode" : "UPI",

"status" : "SUCCESS"

}

Response Body Sent by Paysharp for Pending Case

{

"code" : 200,

"message" : "success",

"data" : {

"orderId" : "502001051004",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_dedc619auJz3YB09687uht",

"refundPaysharpReferenceNo" : "REFUND222b392bl9VMW3uC4a8eef",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"mode" : "UPI",

"status" : "PENDING"

}

Response Body Sent by Paysharp for Failure Case

{

"code" : 200,

"message" : "success",

"data" : {

"orderId" : "602001051004",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_dedc619auJz3YB0m8hb4rd",

"refundPaysharpReferenceNo" : "REFUND342b392bl9VMW3uC4a8egh",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "228200442368",

"refundDate" : "2025-02-11T11:45:51+05:30",

"mode" : "UPI",

"status" : "FAILURE",

"isRecredited" : true

}

Refund Webhook

Our system will call your provided webhook URL to post the refund status once the refund is processed. If your webhook does not respond, the call will be marked as failed.

Your webhook must respond in JSON format with the following structure:

content-type: application/json

Request

Parameters	Datatype	Description
orderId	string	Returns the order Id of the original UPI transaction.
customerId	string	Returns the customer Id of the original UPI transaction.
paysharpReferenceNo	string	Paysharp reference number for the original UPI transaction.
refundPaysharpReferenceNo	string	Reference number generated for the refund transaction.
refundProduct	string	Refund Product Always returns as "UPI".
refundType	string	Allowed values: FULL - Full refund PARTIAL - Partial refund
refundAmount	number	Amount refunded to the customer for the order.
fee	number	Refund transaction fee.
tax	number	Tax applied to the refund transaction.
totalFee	number	Sum of fee and tax.
refundUtrNumber	string	Unique Transaction Reference (UTR) number provided by the bank for the refund transaction.
refundDate	datetime	Refund date in ISO 8601 format.
mode	string	Always returns as “UPI”.
status	string	Status of the refund: SUCCESS - For successful refund case FAILURE - In case refund failed
attemptCount	number	Number of times the webhook invoked.
source	string	Source of refund initiation: REFUND_UI - Via web dashboard UI REFUND_API - Via API

Example

{

"orderId" : "202001051005",

"customerId" : "C_1112",

"paysharpReferenceNo" : "upi_dedc619auJz3YB096Se7Rn",

"refundPaysharpReferenceNo" : "REFUND190c392bl9VMW3uC4a8eNW",

"refundProduct" : "UPI",

"refundType" : "PARTIAL",

"refundAmount" : 200,

"fee" : 5,

"tax" : 0.90,

"totalFee" : 5.90,

"refundUtrNumber" : "238200422359",

"refundDate" : "2025-04-19T11:25:51+05:30",

"mode" : "UPI",

"status" : "SUCCESS",

"attemptCount" : 1,

"source" : "REFUND_UI"

}

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" : 9003,

"message" : "Maximum of 3 partial refunds are allowed per transaction"

}

Possible Errors

Error Codes	Error Messages
9001	Transaction not found.
9002	Insufficient balance. Please ensure sufficient funds are available before initiating a refund.
9003	Maximum of 3 partial refunds are allowed per transaction.
9004	New refund requests cannot be processed while a previous refund request is still pending.
9005	Full refund is not permitted once a partial refund has been processed.
9006	Partial refund amount must not be equal to or greater than the original transaction amount.
9007	Refunds cannot be processed for transactions older than 90 days.
9008	Invalid refund type. The refundType must be either FULL or PARTIAL.
9009	Refund already processed for this transaction.