This API allows the platform to create a payment link/intent flow using Decentro's UPI stack.
Important Note
Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.
Overview
This API lets a platform collect funds using Decentro's Payment link capability on its v3 stack.
Flow
Below is the flow for using the payment link/intent flow through Decentro.
- The platform creates a payment link using this API and the Endpoint by passing the consumer_urn shared by Decentro before going live.
- 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 (Basic) or the Get Transaction Status (Advance).
- The platform can use the shortened link directly on a web/app flow or use individual deep links by passing generate_psp_uri as true if needed else pass false.
- The platform embeds the link in its checkout flow, app, or any third-party system and sends it directly to the end customer via SMS, WhatsApp, etc.
- The payer clicks on the link and authenticates the payment by entering their UPI MPIN on the app of their choice.
- 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 (Basic) or the Get Transaction Status (Advance) API, which can be done using Decentro's transaction ID, which is shared in the response of this API.
Key Points
Below are the key points about the payment link workflow.
- If the payer doesn't pay or attempts to pay before the expiry time, the platform must create a new link for the payer to authorize.
- If the payer uses the link to land on a UPI app after the expiry time, the payer may still be able to complete the transaction.
- If the payer clicks on the link after expiry, the payer cannot be redirected to any UPI app since the transaction will be marked as expired.
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/link |
| Production | https://api.decentro.tech/v3/payments/upi/link |
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 |
| transaction_status | The status of the transaction. This is typically pending unless there's an error in creating the link. |
| upi_uris | A nested response containing the common URI or deep links for key apps. |
| common_uri | A UPI protocol-based link that the payer can use to pay using any app. |
| gpay_uri | A Google Pay protocol-based link that the payer can use to pay using Google Pay. |
| phonepe_uri | A PhonePe protocol-based link that the payer can use to pay using Phonepe Pay. |
| paytm_uri | A PayTm protocol-based link that the payer can use to pay using PayTm. |
| cred_uri | A cred protocol-based link that the payer can use to pay using cred. |
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. |
Simulation Data
Overview
Decentro's simulation data helps developers simulate all the real-world scenarios when using the Payment Link API.
This requires the platform to use standard request payloads to handle scenarios for each API and scenario, as mentioned below.
The platform will need to whitelist their IP and configure callback endpoints with Decentro if they wish to handle the flow. Please reach out to us at [email protected] for the same.
Flow
Below is the flow for testing the payment link API testbed.
- Generate a payment link with the 'amount' parameter as as mentioned in the testbed data section.
- Obtain the generated link in the generate payment link API response.
- After 10 seconds, check the payment's status by using the decentro_txn_id received in the response and input it into the decentro_txn_id query param field in the Get Transaction Status API.
- After another 10 second delay from step 3, the client will receive the terminal status depending on the Amount passed in Step 1.
- To test the scenario where the payment link expires, include the necessary time value in the expiry_time field when generating the link. Once the expiry time window has passed, repeat step 3 to receive the terminal status as EXPIRED. Alternatively, user will receive a EXPIRED callback after 10 seconds.
Note: When the transaction status is SUCCESS or FAILURE, Decentro intentionally delays the response by 10 seconds to mimic the time it takes for the user to authenticate the payment via the UPI app by entering their UPI MPIN. Till 10 seconds user will receive transaction status as PENDING
Test Data
Please refer to the table below for Amount v/s transaction status test cases in staging scenarios. Please pass only the amount mentioned below for the scenario in the 'amount' field in the request payload for the scenario that is being simulated.
| Amount | Transaction Status | Test Scenario |
|---|---|---|
| 10 | SUCCESS | Payment link is created & Transaction status is SUCCESS |
| 20 | FAILURE | Payment link is created & Transaction status is FAILURE |
| 30 | REQUEST_UNINITIALIZED | Payment link is not created & payment link status is UNINITIALIZED |
| 40 | PENDING | Payment link is created & Transaction status is PENDING |
Testbed Endpoints
Decentro's Generate Payment Link API's testbed can be used on the endpoint: https://staging.api.decentro.tech/v3/payments/upi/link