Penny Pull - Intent API

This API allows the platform to create an Intent link using Decentro's Penny pull stack.

πŸ™Œ

Important Note

Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.

Overview

This API empowers platforms to authenticate the bank account information of their customers by leveraging Decentro's Penny Pull/Reverse Penny Drop stack capability through the intent flow where the payer doesn't have to enter a VPA (UPI ID).

Flow

Below is the flow for using the Penny pull intent link/intent flow through Decentro.

  1. The platform creates a penny pull intent link using this API endpoint and reference_id in the request body.
  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 API or map the same from the callback triggered by Decentro to the platform.
  3. The platform can use the shortened link directly on a web/app flow or use individual deep links by passing generate_uri as 1.
  4. The platform sends the shortened link directly to the end customer via SMS, WhatsApp, etc., or can embed it on its web/app.
  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 Penny Pull Transaction Status Callback to the client's pre-configured endpoint with the transaction status.
  7. Alternatively, the platform can check the status of the Intent 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.
  8. The payer gets a refund of their INR 1 transaction if successful within 2 working days of the transaction being completed.

Key Points

Below are the key points about the intent link workflow.

  • If the payer uses the link to land on a UPI app within the expiry time of 10 minutes, the payer should be able to complete the transaction.
  • If the payer uses the link to land on a UPI app after the expiry time of 10 minutes, the payer should not 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.

Simulation Data

Below is the test data that can be used by platforms to test out standard scenarios for Penny Pull - Intent API.
The platform is expected to pass the parameters as-is to get the intended scenario.

πŸ“˜

Note - Simulation Data

To test Simulation Staging data for Penny Pull - Intent API, please use the following API Endpoint: https://in.staging.decentro.tech/v2/payments/penny_pull

Steps to use this data:

  1. In the request body, pass request values as shared below in the table, depending on the scenario to be tested.
  2. Trigger the Create Intent API with the choice(s) chosen in Step 1.
  3. Based on the values provided in Step 1 for each request parameter, the API response will confirm the creation of a short link, QR code (with or without a logo), and PSP-specific deep links.
  4. In the API response, locate the field labeled decentroTxnId and make a note of it. This decentroTxnId will be utilised to retrieve the transaction status using the Get Transaction Status API, indicating whether the payer has completed the payment or not.
  5. To retrieve the terminal status of the transaction, utilize the Simulation Data obtained from the Get Transaction Status API page.
Request bodyRequest valueTest case
generate_qr0 or 10/1 depending on the choice to generate QR. 1 for generating QR and 0 for not generating QR
generate_uri0 or 10/1 depending on the choice to generate UPI data URI to implement customized flow based on URI data for GPay, PhonePe, PayTm UPI apps.
customized_qr_with_logo0 or 10/1 depending on whether you want to get a customised QR code with logo

Response Parameters

Below are the parameters propagated by Decentro in the response.

ParametersDescription
decentroTxnIdA unique transaction ID from Decentro against the incoming intent request
statusStatus of the Intent API request
responseCodeA unique response code mapped with API request status.
messageStatus description of the intent request
validationShortLinkShortened intent link sent by Decentro to the platform
validationStatusStatus of the transaction once payment link is sent to the merchant
Possible value: β€œPENDING”
validationDescriptionDecentro description regarding the status of the API request.
encodedDynamicQrCodeIf generate_qr =1, then in response, an encoded dynamic QR code is passed.
gpayUriA Google Pay protocol-based link that the payer can use to pay using Google Pay.
phonepeUriA PhonePe protocol-based link that the payer can use to pay using PhonePe.
paytmUriA PayTm protocol-based link that the payer can use to pay using PayTm.
responseKeyResponse key documenting the status of the API hit and various errors as mentioned here

Response Keys

Below are the response keys propagated by Decentro in the responseKey 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 KeyScenario
successful_payment_link_createdIntent Link created Successfully
error_invalid_reference_idReference URL is not of type string
error_duplicate_reference_idDuplicate Request Reference ID
error_malformed_requestMalformed request detected.
error_unsanitized_valuesUnsanitized values detected for key(s): purpose_message. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry.
error_invalid_generate_QR_valueInvalid value entered for Generate QR. Generate QR can be either 0 or 1.
Hint : generate_qr (int)
error_invalid_generate_uri_valueInvalid value entered for Generate URI flag. Generate URI can be either 0 or 1. Hint : generate_uri (int)
error_invalid_customized_qr_with_logoInvalid value entered for Customized QR with logo flag. Value can be either 0 or 1. Hint : generate_customized_qr_with_logo (int)
error_missing_reference_idRequest reference id cannot be null or empty. Hint: reference_id (string)
error_invalid_credentialsInvalid authentication credentials
error_missing_credentialsNo API key found in request
error_invalid_client_credentialsAuthentication failed. Please use valid Client ID and Client Secret.
error_empty_client_secretClient Secret cannot be empty. Hint: client_secret (string)
error_unauthorized_moduleAuthentication failed for accessing the module
error_empty_module_secretModule Secret cannot be empty. Hint: module_secret (string)
error_company/account_disabledUPI Credit transactions are disabled for the company/account.
error_invalid_methodThe method is not allowed for the requested URL.
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_incorrect_length_reference_idReference ID needs to be between 5 and 50 characters

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