This API allows the platform to fetch the status of a transaction intiated through a payment link/collect request/dynamic QR code.
Important Note
Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.
Overview
This API allows a platform to fetch the status of a transaction undertaken through any of the flows below.
- Generate payment link API
- Issue Collect Request
- Generate Dynamic QR
Note: this API doesn't allow the platform to check the status of a transaction like a push transaction or a static QR.
Flow
This API is an alternative to the Terminal Transaction Status Callback/Webhook. The platform should use this only if a callback hasn't been acknowledged or transaction confirmation hasn't been received.
- The platform consumes this API to get the latest status of an initiated transaction using the Decentro transaction ID received from Generate payment link API, Generate Dynamic QR.
- In this API, Decentro relays the transaction status via the transaction_status field. The default status will always be 'PENDING' unless the payer authorizes a payment.
- In case multi attempt is enabled, checking the payment status will return the payment link status (SUCCESS, PENDING, EXPIRED).
- In case multi attempt is disabled, checking the payment status will return the payment link status (SUCCESS, PENDING, FAILED, EXPIRED).
To know the status of each attempt made by the payer, client can consume GTS advance.
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/transaction/status?{decentro_txn_id} |
| Production | https://api.decentro.tech/v3/payments/transaction/status?{decentro_txn_id} |
Response Parameters
Below are the parameters propagated by Decentro in the response.
| Parameters | Description |
|---|---|
| decentro_txn_id | A unique transaction ID from Decentro for checking the transaction status and refund status. |
| api_status | Status of the API hit. Note that this is not the status of the transaction. |
| message | API status message. Note that this is not about the status of the transaction. |
| response_key | Response key documenting the status of the API hit and various errors as mentioned here. |
| transaction_status | The status of the transaction can be one of the values - SUCCESS, FAILURE, PENDING, EXPIRED. |
| transaction_status_description | Description message of the transaction status received. |
| bank_reference_number | The unique transaction reference number from the bank partner. |
| npci_txn_id | A unique transaction id generated by NPCI for each transaction. |
| transaction_authentication_timestamp | The timestamp at which the user entered the MPIN and authenticated the payment. |
| error_key | Indicates the entity responsible for failure. Applicable only in case of failed transaction. Please refer to the Error Keys section for details. |
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 transaction status is relayed only after the payer authorizes payment.
| response key | Message |
|---|---|
| error_no_transaction_found | This transaction was not found in our system. If there was any debit, it would have already been reversed. Please retry the corresponding initiate payment transaction. |
| success_transaction_status_successful | UPI Transaction Status processed successfully. |
| success_transaction_status_pending | UPI Transaction Status processed successfully. |
| success_transaction_status_failure | UPI Transaction Status processed successfully. |
| success_transaction_status_expired | UPI Transaction Status processed successfully. |
| error_invalid_provider | Given transaction does not belong to the origianal provider. |
| error_provider_error | Error while fetching transaction status from provider. |
| error_api_access_error | Error while accessing the API. Please reach out to [email protected] for any queries. |
| error_authentication_request | Error while authenticating the request. |
| error_unauthorized_request | Unauthorized request. |
| error_plan_not_configured | Plan not configured. |
| error_plan_not_found | Plan not found. |
| error_duplicate_transaction | Duplicate transaction found. |
| success_refund_status_successful | UPI Refund Status processed successfully |
| success_refund_status_failure | UPI Refund Status processed successfully |
Error Keys
Decentro intimates the platform about the error leg i,e where the error has occurred in the transaction using the 'error_key' in the callback payload. Please note that error keys are for the platform's use, and standalone is not recommended for end-user messaging.
Below are the values propagated by Decentro, as well as the associated interpretation.
| Error Key | Description |
|---|---|
| error_at_remitter_bank | The transaction failed due to an issue at the payer's bank, such as limits breached or an account frozen. |
| error_at_beneficiary_bank | The transaction failed due to an issue at the Decentro's bank partner's end. |
| error_at_payer_psp | The transaction failed due to an issue at payer PSP, i.e., the UPI app used by the payer to authorize the transaction. |
| error_at_payee_psp | The transaction failed due to payee PSP, i.e., Decentro's partner bank's end. |
| error_at_npci | The transaction failed due to an issue at the NPCI level |