post https://staging.api.decentro.tech/v3/payments/upi/collect
This API is under development. Details will be added once the APIs are signed off in staging/QA.
Overview
This API lets a platform collect funds using Decentro's Collect request capability on its v3 stack.
Flow
Below is the flow for using the collect request flow through Decentro.
- The platform initiates the collect request using this API and Endpoint, by passing the consumer_urn shared by Decentro along with the UPI VPA of the payer.
- Decentro relays the status of the link creation using response keys and the Decentro transaction ID, which can be used to check the status through the Get Transaction Status.
- The payer receives a payment request intimation through a push notification on their mobile or an SMS from their bank.
- The payer opens the relevant UPI app and authenticates the payment by entering their UPI MPIN.
- Decentro triggers the Terminal Transaction Status Callback/Webhookto the client's pre-configured endpoint with the transaction status.
- Alternatively, the platform can check the status of the payment link using the Get Transaction Status API, which can be done using Decentro's transaction ID, which is available as the response in this API.
Please Note: The Auto-retry functionality is not available for collect requests.
API Endpoints
Below are the API endpoints to be used by the platform basis the environments.
Please Note: This API is currently available on the Staging/Sandbox environment only.
| Environment | Endpoint |
|---|---|
| Staging/Sandbox | https://staging.api.decentro.tech/v3/payments/upi/collect |
| Production | https://api.decentro.tech/v3/payments/upi/collect |
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, refund, etc. |
| 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 |
| data | The JSON object containing the transaction details. |
| transaction_status | The status of the transaction. This is typically pending unless there's an error in sending the collect request. |
| bank_reference_number | The unique transaction reference number from the bank partner mapped to payment. |
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_payment_link_created | Payment Link created Successfully. |
| error_account_disabled | Your account has been disabled. Please reach out to support |
| error_malformed_request | Malformed request detected. |
| error_empty_request | Request body is empty. Kindly check the payload and retry. |
| error_invalid_method | The method is not allowed for the requested URL. |
| error_unsanitized_values | Unsanitized values detected for key(s): <KEY NAME(s)>. Kindly sanitize the corresponding values by removing unicode, non-ascii, and special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry. |
| error_invalid_client_id | Authentication failed. Please use a valid Client ID. |
| error_empty_client_id | Client ID cannot be empty. Hint: client_id (string) |
| error_invalid_format_client_id | Client ID is not of type string. Hint: client_id (string) |
| error_invalid_client_secret | Authentication failed. Please use a valid Client Secret. |
| error_empty_client_secret | Client Secret cannot be empty. Hint: client_secret (string) |
| error_invalid_format_client_secret | Client Secret is not of type string. Hint: client_secret (string) |
| error_invalid_jwt | Authentication failed. Token either expired or invalid. |
| error_empty_jwt | JWT cannot be empty. Hint: JWT (JSON) |
| error_invalid_format_jwt | JWT is not of type JSON. Hint: JWT (JSON) |
| error_invalid_bearer_token | Authentication failed. Please use a valid bearer token. |
| error_empty_bearer_token | Bearer Token cannot be empty. Hint: bearer_token (string) |
| error_invalid_format_bearer_token | Bearer Token is not of type string. Hint: bearer_token (string) |
| error_invalid_consumer_urn | Consumer URN passed is not valid. |
| error_empty_consumer_urn | Consumer URN cannot be empty. Hint: consumer_urn (string) |
| error_invalid_format_consumer_urn | Consumer URN is not of type string. Hint: consumer_urn (string) |
| error_invalid_reference_id | Reference ID is not valid. |
| error_empty_reference_id | Reference ID cannot be empty. Hint: reference_id (string) |
| error_invalid_format_reference_id | Reference ID is not of type string. Hint: reference_id (string) |
| error_duplicate_reference_id | Duplicate Reference ID. Please pass an unique value. |
| error_incorrect_length_reference_id | Reference ID needs to be between 5 and 50 characters |
| error_invalid_amount | Please pass the amount value with up to two decimals places only. Hint: amount (float) |
| error_empty_amount | Amount cannot be empty. Hint: amount (float) |
| error_invalid_format_amount | Amount is not of type float. Hint: amount (float) |
| error_incorrect_length_amount | Amount needs to be between INR and . |
| error_empty_purpose_message | Purpose message cannot be empty. Hint: purpose_message (string) |
| error_invalid_format_purpose_message | Purpose message is not of type string. Hint: purpose_message (string) |
| error_incorrect_length_purpose_message | Purpose message needs to be between 5 and 50 characters |
| error_invalid_expiry_time | Expiry Time needs to be strictly greater than 0. Hint: expiry_time (int) |
| error_empty_expiry_time | expiry_time cannot be empty. Hint: expiry_time (int32) |
| error_invalid_format_expiry_time | Expiry Time should be of type integer. Hint: expiry_time (int) |
| error_incorrect_length_expiry_time | Expiry Time cannot exceed 1440 minutes. |