post https://staging.api.decentro.tech/v3/payments/upi/refund
This API enabled you to issue refunds for a successful payment.
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 and the Generate Dynamic QR API, by passing the value under original_decentro_txn_id parameter.
- We support partial refunds and 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 UPI ID) 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 "original_decentro_transaction_id" parameter.
- Once the refund is processed, Decentro shares the status (REFUNDED or REFUND_FAILED) via the Transaction Status Callback/Webhook .
- Alternatively, the platform can query the refund status via the Get Transaction Status (Basic and Advance) API.
Please Note
- A refund request can be initiated at a Transaction or a Transaction Attempt level via the Issue Refund API.
- Transaction level parameters: 'original_decentro_txn_id' and 'original_reference_id'
- Transaction Attempt level parameters: 'bank_reference_number' and 'original_attempt_decentro_txn_id'
- Refunds can only be initiated when the status value, for a given Transactions or Transaction Attempt, is "SUCCESS".
- We refer to the successful payment, by the end customer, as the 'Credit Transaction'. The refund is referred to as the 'Debit Transaction'.
- We do not update the status of the payment request (credit transaction) when the refund is requested.
- If you initiate the GTS Advance) API with the details of the credit transaction, the API response will contain the details of the associated refund (debit) transactions.
- If a Transaction Attempt was "AUTO REFUNDED" or "RELEASED" (corresponding action value), the Issue Refund API will throw an error if the platform tries to initiate a refund.
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 | Purpose message needs to be between 5 and 50 characters |
| 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_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 |
| error_refund_attempt_not_identified | Multiple successful attempts detected for this payment. Please pass the original_attempt_decentro_txn_id for refunding the attempt. |