Refunds
With the PayU, you can easily process refunds for payments that have been successfully completed. When a refund is initiated, the system ensures a efficient transfer of the refunded amount directly to the buyer's account.
Creating a Refund
In PayU, you can refund transactions in two ways: full and partial.
To initiate a refund, make a POST request to the /api/v2_1/orders/{orderId}/refunds
endpoint.
You can also refund transactions from the management panel. Just find the transaction in the transaction list and use the Refund action in the Action column.
For PayU | Pay later payment method funds are transferred to a credit provider.
Full Refund
A full refund is exactly as it sounds - a refund of the entire amount of the transaction. If you don't specify the refund amount
in your refund request, the system will automatically handle it as a full refund.
curl -X POST https://secure.payu.com/api/v2_1/orders/H9LL64F37H160126GUEST000P01/refunds \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
"refund": {
"description": "Refund"
}
}'
For details on parameters, please refer to Create a Refund section in the PayU API Reference.
Partial Refund
When processing partial refunds in PayU, you must explicitly specify the amount
parameter in your refund request. Always ensure that the amount is specified in the lowest unit of the currency used for the initial order.
For example, in Poland (PLN), the lowest currency unit is the penny, which equals 1/100 PLN. So, for a partial refund of 10 PLN, you should specify the amount
as 1000 (representing 1000 pennies).
You can send several partial refund requests for each single order. The total value of the requests must not exceed the order value.
You can also execute multiple partial refunds simultaneously. To achieve this, you need to include the extRefundId
parameter in your refund request. However, if partial refunds won't be performed more than once per second, the extRefundId
parameter is not mandatory.
curl -X POST https://secure.payu.com/api/v2_1/orders/H9LL64F37H160126GUEST000P01/refunds \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
"refund": {
"description": "Refund",
"amount": 1000
}
}'
For details on parameters, please refer to Create a Refund section in the PayU API Reference.
As soon as the PayU system receives a request, it will confirm this fact with a message containing a relevant status.
Refund Response
Accepted request will be confirmed by a response with containing appropriate status.
- SUCCESS
- ERROR
{
"orderId": "ZXWZ53KQQM200702GUEST000P01",
"refund": {
"refundId": "5000009987",
"extRefundId": "20200702091903",
"amount": "21000",
"currencyCode": "PLN",
"description": "5000009987 Refund Accepted",
"creationDateTime": "2020-07-02T09:19:03.896+02:00",
"status": "PENDING",
"statusDateTime": "2020-07-02T09:19:04.013+02:00"
},
"status": {
"statusCode": "SUCCESS",
"statusDesc": "Refund queued for processing"
}
}
Highlighted in the response body is the refundId
parameter which you can use to retrieve the informations about specific refund.
{
"status": {
"statusCode": "ERROR_VALUE_MISSING",
"severity": "ERROR",
"code": "8300",
"codeLiteral": "MISSING_REFUND_SECTION",
"statusDesc": "Missing required field"
}
}
A refund request that has been properly accepted by the PayU system may be cancelled in the management panel.
Error Codes
The status
object present in each response indicates the status of the created refund. In the event of incorrectly created refunds, an error response will be triggered, providing information about the issue. Below is a list of possible error codes.
StatusCode | CodeLiteral | Code | Description |
---|---|---|---|
ERROR_VALUE_MISSING | MISSING_REFUND_SECTION | 8300 | Request lacks refund object. |
OPENPAYU_BUSINESS_ERROR | TRANS_NOT_ENDED | 9101 | Transaction has not been finalized. |
OPENPAYU_BUSINESS_ERROR | NO_BALANCE | 9102 | Lack of funds in account. |
OPENPAYU_ERROR_VALUE_INVALID | AMOUNT_TO_BIG | 9103 | Refund amount exceeds transaction amount. |
OPENPAYU_ERROR_VALUE_INVALID | AMOUNT_TO_SMALL | 9104 | Refund value is too small. |
OPENPAYU_BUSINESS_ERROR | REFUND_DISABLED | 9105 | Refunds have been disabled. |
OPENPAYU_BUSINESS_ERROR | REFUND_TO_OFTEN | 9106 | Too many refund attempts have been made. |
OPENPAYU_ERROR_VALUE_INVALID | PAID | 9108 | Refund was already created. |
OPENPAYU_ERROR_INTERNAL | UNKNOWN_ERROR | 9111 | Unknown error. |
OPENPAYU_BUSINESS_ERROR | REFUND_IDEMPOTENCY_MISMATCH | 9112 | extRefundId was re-used and other params do not match the values sent during the first call. |
OPENPAYU_BUSINESS_ERROR | TRANS_BILLING_ENTRIES_NOT_COMPLETED | 9113 | Shop billing has not yet been completed. |
OPENPAYU_BUSINESS_ERROR | TRANS_TOO_OLD | 9114 | The available time for refund has passed. |
OPENPAYU_ERROR_VALUE_INVALID | REMAINING_TRANS_AMOUNT_TOO_SMALL | 9115 | Transaction amount that remains after refund creation will be too small to make another refund. |
Retrieving Refund Data
You have two options to obtain refund information in PayU. Firstly, you can retrieve the list of refunds for the specified orderId
. Secondly, you can fetch specific refund data using the refundId
that was returned in response to the refund creation request.
When making GET requests, please remember not to include any data in the request body, as specified in the RFC 9110 standard. Requests that do not adhere to this requirement will be rejected by PayU with an HTTP 403 status.
Retrieving List of Refunds
To retrieve the list of refunds created for a specific orderId
, make a GET request to the /api/v2_1/orders/<orderId>/refunds
endpoint. The response will provide you with a comprehensive list of refunds created for that particular order.
{
"refunds": [
{
"refundId": "5000000142",
"extRefundId": "postman_refund1_QX9ZR7M6QP200601GUEST000P01",
"amount": "400",
"currencyCode": "EUR",
"description": "Order refund",
"creationDateTime": "2020-06-01T13:05:39.489+02:00",
"statusDateTime": "2020-06-01T13:06:03.530+02:00",
"status": "FINALIZED"
},
{
"refundId": "5000000143",
"extRefundId": "postman_refund2_QX9ZR7M6QP200601GUEST000P01",
"amount": "400",
"currencyCode": "EUR",
"description": "Order refund",
"creationDateTime": "2020-06-01T13:18:03.648+02:00",
"statusDateTime": "2020-06-01T13:18:33.661+02:00",
"status": "FINALIZED"
}
]
}
For details on response fields, please refer to Retrieve all Refunds Data section in our API Reference.
Retrieving Specific Refund
To obtain specific data about a refund, make a GET request to the /api/v2_1/orders/<orderId>/refunds/<refundId>
endpoint. In response, you will receive detailed information about the refund associated with the provided refundId
. This allows you to access and review specific refund details as needed.
{
"refundId": "5000000143",
"extRefundId": "postman_refund2_QX9ZR7M6QP200601GUEST000P01",
"amount": "400",
"currencyCode": "EUR",
"description": "Order refund",
"creationDateTime": "2020-06-01T13:18:03.648+02:00",
"statusDateTime": "2020-06-01T13:18:33.661+02:00",
"status": "FINALIZED"
}
For details on response fields, please refer to Retrieve Specific Refund Data section in our API Reference.
Refund Processing Error Codes
In case of an incorrect refund processing, such as a failure in the return authorization at the provider's end, you will receive an error response containing detailed information. Additionally, the response will include an additional statusError
field, which provides further insights into the encountered issue.
{
...
"statusError": {
"code": "PROVIDER_TECHNICAL_ERROR",
"description": "Temporary problem on Provider Side"
}
}
The table lists the error codes that can occur during refund processing and what to do in each case:
ErrorCode | Description | Recommended Procedure |
---|---|---|
BANK_DECLINED | Bank rejected refund. | Please register a refund again. If the error occurs repeatedly please contact PayU support so that a refund to a bank account can be registered. |
PROVIDER_DECLINED | Provider rejected refund. | Please register a refund again. If the error occurs repeatedly please contact PayU support so that a refund to a bank account can be registered. |
PROVIDER_LIMIT_ERROR | Some limit was exceeded on Provider side. | Please register a refund again. If the error occurs repeatedly please contact PayU support. |
PROVIDER_SECURITY_ERROR | Some security rule was broken. | Please register a refund again. If the error occurs repeatedly please contact PayU support. |
PROVIDER_TECHNICAL_ERROR | Temporary problem on Provider Side. | Please register a refund again. If the error occurs repeatedly please contact PayU support. |
BANK_UNAVAILABLE_ERROR | Bank supplied by provider is temporary unavailable. | Please register a refund again after some time. |
REFUND_TOO_LATE | Time to register refund was exceeded. | Please contact PayU support so that a refund to a bank account can be registered. |
TECHNICAL_ERROR | Some technical problem occured. | Please contact PayU support. |
REFUND_TOO_FAST | Provider cannot permit to register too many refunds in given period of time. | Please register a refund again after some time. |
REFUND_IMPOSSIBLE | Provider permanently rejected refund. | Please contact PayU support so that a refund to a bank account can be registered. |