This API is under development. Details will be added once the APIs are signed off in staging/QA.
Overview
This API can be used by the platform to refund a transaction back to the source i,e the VPA from which payer undertook a transaction.
This can be processed for any transaction undertaken through the below modes.
- Generate payment link API
- Issue Collect Request
- Generate Dynamic QR
Flow
Below is the flow for initiating the refunds through Decentro's stack.
- The platform consumes this API to refund a successful transaction using the Decentro transaction ID received from Generate payment link API, Generate Dynamic QR, or Issue collect request by passing the value under originaldecentro txn_id parameter.
- The platform can choose to refund the complete transaction or part of it by passing the requisite value under the amount parameter.
- Decentro checks the platform's available balance and initiates the refund to the source VPA (payer VPA) if the transaction is found.
- Decentro rejects the request for a refund if the transaction is not found at its end due to an invalid value passed in the originaldecentro txn_id parameter.
Please note that Decentro might not reverse the commission for the original transaction. This will depend on the commercial agreement that the platform will have with Decentro.
API Endpoints
Below are the API endpoints to be used by the platform basis the environments.
| Environment | Endpoint |
|---|---|
| Staging/Sandbox | https://staging.api.decentro.tech/v3/payments/upi/refund |
| Production | https://api.decentro.tech/v3/payments/upi/refund |
Response Keys
Below are the response keys propagated by Decentro in the response_key parameter, which cover all the scenarios a platform can encounter.
Please note that the below keys don't include transaction-related response keys since the status of the transaction is relayed only after the payer authorizes payment.
| Response Key | Message |
|---|---|
| success_refund_status_pending | Transaction refund request processed successfully |
| success_refund_status_failed | Transaction refund request processed successfully |
| success_refund_status_success | Transaction refund request processed successfully |
| error_invalid_reference_id | Reference URL is not of type string |
| error_duplicate_reference_id | Duplicate Request Reference ID |
| error_malformed_request | Malformed request detected. |
| error_unsanitized_values | Unsanitized values detected for key(s): purpose_message. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry. |
| error_invalid_purpose_message_length | Length of Purpose Message cannot be greater than X |
| error_invalid_purpose_message | Purpose Message is not of type string. Hint : purpose_message (string) |
| error_missing_reference_id | Request reference id cannot be null or empty. Hint: reference_id (string) |
| error_missing_purpose_message | Purpose Message cannot be null or empty. Hint : purpose_message (string) |
| error_invalid_credentials | Invalid authentication credentials |
| error_missing_credentials | No API key found in request |
| error_invalid_client_credentials | Authentication failed. Please use valid Client ID and Client Secret. |
| error_empty_client_secret | Client Secret cannot be empty. Hint: client_secret (string) |
| error_unauthorized_module | Authentication failed for accessing the module |
| error_empty_module_secret | Module Secret cannot be empty. Hint: module_secret (string) |
| error_company/account_disabled | UPI Credit transactions are disabled for the company/account. |
| error_no_transaction_found | No such transaction found at our end. Please check the values and retry |
| error_no_transaction_identifier_found | Any one value should be present out of transaction_id, original_reference_id and bank_reference_number.Please check the documentation and provide values accordingly. |
| error_provider_error | Unexpected response received from underlying provider |