post https://in.staging.decentro.tech/v2/payments/penny_pull
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.
- The platform creates a penny pull intent link using this API endpoint and reference_id in the request body.
- 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.
- The platform can use the shortened link directly on a web/app flow or use individual deep links by passing generate_uri as 1.
- The platform sends the shortened link directly to the end customer via SMS, WhatsApp, etc., or can embed it on its web/app.
- The payer clicks on the link and authenticates the payment by entering their UPI MPIN on the app of their choice.
- Decentro triggers the Penny Pull Transaction Status Callback to the client's pre-configured endpoint with the transaction status.
- 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.
- 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.
| Environment | Endpoint |
|---|---|
| Staging / Sandbox | https://in.staging.decentro.tech/v2/payments/penny_pull |
| Production | https://in.decentro.tech/v2/payments/penny_pull |
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:
- In the request body, pass request values as shared below in the table, depending on the scenario to be tested.
- Trigger the Create Intent API with the choice(s) chosen in Step 1.
- 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.
- 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.
- To retrieve the terminal status of the transaction, utilize the Simulation Data obtained from the Get Transaction Status API page.
| Request body | Request value | Test case |
|---|---|---|
| generate_qr | 0 or 1 | 0/1 depending on the choice to generate QR. 1 for generating QR and 0 for not generating QR |
| generate_uri | 0 or 1 | 0/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_logo | 0 or 1 | 0/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.
| Parameters | Description |
|---|---|
| decentroTxnId | A unique transaction ID from Decentro against the incoming intent request |
| status | Status of the Intent API request |
| responseCode | A unique response code mapped with API request status. |
| message | Status description of the intent request |
| validationShortLink | Shortened intent link sent by Decentro to the platform |
| validationStatus | Status of the transaction once payment link is sent to the merchant Possible value: “PENDING” |
| validationDescription | Decentro description regarding the status of the API request. |
| encodedDynamicQrCode | If generate_qr =1, then in response, an encoded dynamic QR code is passed. |
| gpayUri | A Google Pay protocol-based link that the payer can use to pay using Google Pay. |
| phonepeUri | A PhonePe protocol-based link that the payer can use to pay using PhonePe. |
| paytmUri | A PayTm protocol-based link that the payer can use to pay using PayTm. |
| responseKey | Response 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 Key | Scenario |
|---|---|
| successful_payment_link_created | Intent Link created Successfully |
| error_invalid_reference_id | Reference URL is not of type string |
| error_duplicate_reference_id | Duplicate Request Reference ID |
| error_malformed_request | Malformed request detected. |
| error_unsanitized_values | Unsanitized values detected for key(s): purpose_message. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ' " ~ ` ? = + ) ( and retry. |
| error_invalid_generate_QR_value | Invalid value entered for Generate QR. Generate QR can be either 0 or 1. Hint : generate_qr (int) |
| error_invalid_generate_uri_value | Invalid value entered for Generate URI flag. Generate URI can be either 0 or 1. Hint : generate_uri (int) |
| error_invalid_customized_qr_with_logo | Invalid 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_id | Request reference id cannot be null or empty. Hint: reference_id (string) |
| error_invalid_credentials | Invalid authentication credentials |
| error_missing_credentials | No API key found in request |
| error_invalid_client_credentials | Authentication failed. Please use valid Client ID and Client Secret. |
| error_empty_client_secret | Client Secret cannot be empty. Hint: client_secret (string) |
| error_unauthorized_module | Authentication failed for accessing the module |
| error_empty_module_secret | Module Secret cannot be empty. Hint: module_secret (string) |
| error_company/account_disabled | UPI Credit transactions are disabled for the company/account. |
| error_invalid_method | The method is not allowed for the requested URL. |
| 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_incorrect_length_reference_id | Reference ID needs to be between 5 and 50 characters |