UPI Refund APIs

Refund API Refund History API Refund Status API Create Dispute API Close Dispute API Refund Webhook API Success and Error Messages Postman Collection

UPI Refund API Reference (v1.0)

UPI Refund Solution

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

}

Create Dispute API

This API allows you to hold a amount for any UPI transaction

URL: /dispute
Method: POST

Request

Parameters	Range	Datatype	Required	Description
complaintReceivedDate		datetime	Y	ComplaintReceivedDate in ISO 8601 format. Date and time when the complaint was received
holdAmount	Min 1	number	Y	Amount put on hold related to the complaint
complaintDetails	Max 5000	string	Y	Description of the issue reported by the customer
complaintReceivedFrom	Max 100	string	Y	Source of the complaint (e.g., Customer, Agent)
paysharpRefNo	Max 50	string	N	Unique reference number for the transaction
complaintReceivedReferenceNo	Max 100	string	N	Optional reference number assigned to the complaint
complaintEmail	Max 250	string	N	Email of the complaint
complaintContactNo	Min 8 – Max 15	string	N	Contact number of the complaint
city	Max 100	string	N	City of the complaint
state	Max 100	string	N	State of the complaint

Response

Parameters	Datatype	Description
holdId	string	Unique holdId for the hold creation
complaintReceivedDate	datetime	ComplaintReceivedDate in ISO 8601 format. Date and time when the complaint was received
holdAmount	number	Amount put on hold related to the complaint
complaintDetails	string	Description of the issue reported by the customer
complaintReceivedFrom	string	Source of the complaint (e.g., Customer, Agent)
paysharpRefNo	string	Unique reference number for the transaction
complaintReceivedReferenceNo	string	Optional reference number assigned to the complaint
complaintEmail	string	Email of the complaint
complaintContactNo	string	Contact number of the complaint
city	string	City of the complaint
state	string	State of the complaint
complaintStatus	string	Current complaint status

Example

Request

{

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

"holdAmount" : 500,

"complaintDetails" : "Transaction amount not credited to beneficiary account",

"complaintReceivedFrom" : "customer",

"paysharpRefNo" : upi_dedc619auJz3YB096Se7Zh,

"complaintReceivedReferenceNo" : "CD189b392bl9VMW3uC4",

"complaintEmail" : "abcemail@abc.com",

"complaintContactNo" : "9111100000",

"city" : "chennai",

"state" : "Tamil Nadu"

}

Response

{

"code" : 200,

"message" : "success",

"data" : {

"holdId" : "69cd0af87dfd33c0000f71a0",

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

"holdAmount" : 500,

"complaintDetails" : "Transaction amount not credited to beneficiary account",

"complaintReceivedFrom" : "customer",

"paysharpRefNo" : upi_dedc619auJz3YB096Se7Zh,

"complaintReceivedReferenceNo" : "CD189b392bl9VMW3uC4",

"complaintEmail" : "abcemail@abc.com",

"complaintContactNo" : "9111100000",

"city" : "chennai",

"state" : "Tamil Nadu",

"complaintStatus" : "OPEN"

}

Close Dispute API

This API allows you to close the complaint for any UPI transaction

URL: /close/{holdId}
Method: GET

Request

Parameters	Range	Datatype	Required	Description
holdId	Max 50	string	Y	Unique holdId for the hold creation

Response

Parameters	Datatype	Description
holdId	string	Unique holdId for the hold creation
complaintReceivedDate	datetime	ComplaintReceivedDate in ISO 8601 format. Date and time when the complaint was received
holdAmount	number	Amount put on hold related to the complaint
complaintDetails	string	Description of the issue reported by the customer
complaintReceivedFrom	string	Source of the complaint (e.g., Customer, Agent)
complaintReceivedReferenceNo	string	Optional reference number assigned to the complaint
complaintEmail	string	Email of the complaint
complaintContactNo	string	Contact number of the complaint
city	string	City of the complaint
state	string	State of the complaint
complaintStatus	string	Current complaint status

Example

Response

{

"code" : 200,

"message" : "success",

"data" : {

"holdId" : "69cd0af87dfd33c0000f71a0",

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

"holdAmount" : 500,

"complaintDetails" : "Transaction amount not credited to beneficiary account",

"complaintReceivedFrom" : "customer",

"paysharpRefNo" : upi_dedc619auJz3YB096Se7Zh,

"complaintReceivedReferenceNo" : "CD189b392bl9VMW3uC4",

"complaintEmail" : "abcemail@abc.com",

"complaintContactNo" : "9111100000",

"city" : "chennai",

"state" : "Tamil Nadu",

"complaintStatus" : "CLOSED"

}

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	Refund already processed for this transaction.
9009	This account does not have the refund product, or it is inactive. Please add or activate it.
9010	paysharpRefNo not found.
9011	Hold detail already exists with the same paysharpRefNo for this account.
9012	HoldId is required.
9013	Complaint already closed.
9014	Unable to close the complaint.
9015	Record not found.
9016	Invalid complaintReceivedDate.