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.
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 Google Pay.
paytm_uriA PayTm protocol-based link that the payer can use to pay using PayTm.

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.
Language
Click Try It! to start a request and see the response here!