Generate Payment Link

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.

  1. The platform creates a payment link using this API and the Endpoint by passing the consumer_urn shared by Decentro before going live.
  2. 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.
  3. 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.
  4. 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.
  5. The payer clicks on the link and authenticates the payment by entering their UPI MPIN on the app of their choice.
  6. Decentro triggers the Terminal Transaction Status Callback/Webhookto the client's pre-configured endpoint with the transaction status.
  7. 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.

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.

Response Parameters

Below are the parameters propagated by Decentro in the response.

ParametersDescription
decentro_txn_idA unique transaction ID from Decentro for checking the transaction status, refund, etc.
api_statusStatus of the API hit. Note that this is not the status of the transaction.
messageAPI status message. Note that this is not about the status of the transaction.
response_keyResponse key documenting the status of the API hit and various errors as mentioned here
transaction_statusThe status of the transaction. This is typically pending unless there's an error in creating the link.
upi_urisA nested response containing the common URI or deep links for key apps.
common_uriA UPI protocol-based link that the payer can use to pay using any app.
gpay_uriA Google Pay protocol-based link that the payer can use to pay using Google Pay.
phonepe_uriA PhonePe protocol-based link that the payer can use to pay using Phonepe Pay.
paytm_uriA PayTm protocol-based link that the payer can use to pay using PayTm.
cred_uriA 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 KeyMessage
success_payment_link_createdPayment Link created Successfully.
error_account_disabledYour account has been disabled. Please reach out to support
error_malformed_requestMalformed request detected.
error_empty_requestRequest body is empty. Kindly check the payload and retry.
error_invalid_methodThe method is not allowed for the requested URL.
error_unsanitized_valuesUnsanitized 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_idAuthentication failed. Please use a valid Client ID.
error_empty_client_idClient ID cannot be empty. Hint: client_id (string)
error_invalid_format_client_idClient ID is not of type string. Hint: client_id (string)
error_invalid_client_secretAuthentication failed. Please use a valid Client Secret.
error_empty_client_secretClient Secret cannot be empty. Hint: client_secret (string)
error_invalid_format_client_secretClient Secret is not of type string. Hint: client_secret (string)
error_invalid_jwtAuthentication failed. Token either expired or invalid.
error_empty_jwtJWT cannot be empty. Hint: JWT (JSON)
error_invalid_format_jwtJWT is not of type JSON. Hint: JWT (JSON)
error_invalid_bearer_tokenAuthentication failed. Please use a valid bearer token.
error_empty_bearer_tokenBearer Token cannot be empty. Hint: bearer_token (string)
error_invalid_format_bearer_tokenBearer Token is not of type string. Hint: bearer_token (string)
error_invalid_consumer_urnConsumer URN passed is not valid.
error_empty_consumer_urnConsumer URN cannot be empty. Hint: consumer_urn (string)
error_invalid_format_consumer_urnConsumer URN is not of type string. Hint: consumer_urn (string)
error_invalid_reference_idReference ID is not valid.
error_empty_reference_idReference ID cannot be empty. Hint: reference_id (string)
error_invalid_format_reference_idReference ID is not of type string. Hint: reference_id (string)
error_duplicate_reference_idDuplicate Reference ID. Please pass an unique value.
error_incorrect_length_reference_idReference ID needs to be between 5 and 50 characters
error_invalid_amountPlease pass the amount value with up to two decimals places only. Hint: amount (float)
error_empty_amountAmount cannot be empty. Hint: amount (float)
error_invalid_format_amountAmount is not of type float. Hint: amount (float)
error_incorrect_length_amountAmount needs to be between INR and .
error_empty_purpose_messagePurpose message cannot be empty. Hint: purpose_message (string)
error_invalid_format_purpose_messagePurpose message is not of type string. Hint: purpose_message (string)
error_incorrect_length_purpose_messagePurpose message needs to be between 5 and 50 characters
error_invalid_expiry_timeExpiry Time needs to be strictly greater than 0. Hint: expiry_time (int)
error_empty_expiry_timeexpiry_time cannot be empty. Hint: expiry_time (int32)
error_invalid_format_expiry_timeExpiry Time should be of type integer. Hint: expiry_time (int)
error_incorrect_length_expiry_timeExpiry 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.

AmountTransaction StatusTest Scenario
10SUCCESSPayment link is created & Transaction status is SUCCESS
20FAILUREPayment link is created & Transaction status is FAILURE
30REQUEST_UNINITIALIZEDPayment link is not created & payment link status is UNINITIALIZED
40PENDINGPayment 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

Language
Click Try It! to start a request and see the response here!