Collections v3

This page gives you an overview of Decentro's collections capabilities on its v3 Payment Aggregator stack.

Introduction

This comprehensive guide provides an in-depth understanding of Decentro's UPI (Unified Payments Interface) APIs, allowing you to seamlessly collect money from your customers or empower partner businesses/SMEs to do the same. The APIs support various methods, including UPI QR codes, payment links, and direct collection requests to designated UPI IDs.

Glossary

Use this glossary to understand the documentation guide better.

TermDescription
PSPPayment Service Provider, UPI apps used by customers for transactions.
Push TransactionCustomers use the UPI handle generated by the platform for customers to pay from their preferred PSP app.
PayerThe entity making the payment. Funds are debited from this entity's account.
PayeeThe entity receiving the payment. Funds are credited to this entity's account.
Single Attempt FlowFlow where customers have a single attempt to authenticate and complete the payment.
Multiple Attempt FlowFlow where customers have multiple attempts to authenticate and complete the payment.
UPI DeeplinksProtocols (deep links) provided for popular PSP apps, reducing the number of clicks in payment link flow.
Validate UPI HandleA flow to check the validity of a UPI-ID before triggering a collection request or UPI payouts.
Issue UPI RefundAPI used to refund initiated UPI collections like collection requests and payment links.
Terminal Transaction Status CallbackCallback triggered by Decentro to the platform for all collection and refund transactions.
On-Hold fundsWhen a successful payment is received after a payment request has expired or duplicate payments are received, merchants can opt to enable the On-Hold functionality.
Auto-Refund fundsWhen a successful payment is received after a payment request has expired or duplicate payments are received, merchants can opt to enable the Auto-Refund functionality.
Release On-Hold fundsAn action performed by the merchant to refund any transaction that is placed On-Hold.
Capture On-Hold fundsAn action performed by the merchant to settle any transaction that is placed On-Hold.

Product Capabilities

UPI Collection Flows

Decentro offers multiple collection flows using UPI:

  • Generate UPI Payment Link: A UPI Link, where the amount is pre-populated and defined by the merchant (payee), which can be used by the end customer (Payer) to make the payment from their preferred UPI (PSP) app. Note: These links should be used on Mobile devices.

  • Generate Dynamic QR Code: A UPI QR code, where the amount is pre-populated and defined by the merchant (payee), which can be scanned by the end customer (Payer) to make the payment from their preferred UPI (PSP) app. Note: These QR codes should be used primarily on desktops but can also be used on mobile devices.

  • Issue collect request: A secure UPI payment flow where a payment notification (aka collect request) is sent to the customer's UPI VPA to complete the payment. The transaction amount will have to be defined before initiating the collect request.

  • Static QR Code: A Static QR code, mapped to the UPI handle assigned to the merchant, can be used by the end customer (Payer) to initiate a payment via their preferred UPI (PSP) app. The payer will have to input the amount manually. Note: Static QRs are generally used in offline retail use cases.

Points to Note:

  • Our Payment Links are versatile and can be used for multiple mobile-based checkouts/transactions.
  • Collect request is the preferred option to ensure the funds are debited from a specific UPI VPA.
  • We recommend using a Static QR solution to enable offline checkouts, such as in retail stores.

Link to Collections v3 APIs of Decentro.

Generate UPI Payment Link

Decentro provides two types of payment links:

  • Generic UPI Payment Link: A standard payment link that can be used across any PSP app. Effortlessly collect payments by embedding the link in your mobile app or sharing it via various channels such as email, SMS, messenger apps, chatbots, and other communication platforms.
  • UPI Deep-links: UPI Payment Links redirect the end customer (payer) directly to a specific UPI (PSP) app to complete the payment if that app is available on the device. Supported apps include Paytm, G-pay, and PhonePe (more will be added).

Flow

Decentro supports broadly 2 flows based on the experience the platform wants to build at its end. This depends on the use case and whether the platform wants to support 1 or multiple transactions against the generic payment link.

  1. Single attempt flow
  • Generate a UPI payment link with the necessary details, such as the transaction amount and expiry period, by triggering the Generate UPI Payment Link API.
  • Share the payment link with the end customer (payer).
  • Customer chooses their preferred UPI (PSP) app and enter their UPI MPIN to complete the transaction.
  • Decentro triggers a terminal transaction status callback when the payment is completed. This callback will help platform understand whether the transaction is successful, failed, or expired.
  • Alternatively, the platform can check the payment status using our Get Transaction Status API.
  1. Multiple attempt flow
  • Generate a payment link with the necessary details, such as the transaction amount and expiry period.
  • Share the payment link with the end customer (payer).
  • Customer chooses their preferred UPI (PSP) app and enter their UPI MPIN to complete the transaction.
  • If the payment fails, the customer can retry multiple times until the payment is completed or the link expires.
  • Decentro triggers a terminal transaction status callback when the payment is completed. This callback will help platform understand whether the transaction is successful or has expired. Note: There is no failure callback in case of multi-attempt flows.
  • Alternatively, platforms can check the payment status using our Get Transaction Status API.

Link to Generate payment link API.

Generate Dynamic QR Code

Decentro provides Dynamic QR codes to merchants that allow their end customers to scan the QR and make the payment for online or offline use-cases.

Flow

  1. Single attempt flow
  • Generate the QR code with necessary details, such as the transaction amount and expiry period, by triggering Generate QR API.
  • Share the QR code, embedded within the short link, with the end customer (payer).
    • The payer can open the short link on a desktop or mobile device to scan and pay.
    • The merchant can display the QR code within their environment via an i-frame to scan and pay.
  • .Customer scans the QR code via the preferred UPI app and enters their UPI MPIN to complete the transaction.
  • Decentro triggers a terminal transaction status callback when the payment is completed. This callback will help platforms understand whether the transaction is successful, failed, or expired.
  • Alternatively, the platform can check the payment status using our Get Transaction Status API.
  1. Multiple attempt flow
  • Generate the QR code with necessary details, such as the transaction amount and expiry period, by triggering Generate QR API.
  • Share the QR code, embedded within the short link, with the end customer (payer).
    • The payer can open the short link on a desktop or mobile device to scan and pay.
    • The merchant can display the QR code within their environment via an i-frame to scan and pay.
  • .Customer scans the QR code via the preferred UPI app and enters their UPI MPIN to complete the transaction.
  • If the payment fails, the customer can retry multiple times until the payment is completed or the QR code expires.
  • Decentro triggers a terminal transaction status callback when the payment is completed. This callback will help platforms understand whether the transaction is successful or has expired. Note: There is no failure callback in case of multi-attempt flows.
  • Alternatively, the platform can check the payment status using our Get Transaction Status API.

Link to Generate Dynamic QR.

Issue Collection request

A collect request is a type of UPI payment that allows you to request money from a specific UPI VPA, which belongs to the payer.

For this collection method to work, the merchant should know the UPI VPA of the end customer (payer). The customer needs to navigate to the app against which the handle is registered and approve the request. This is a vanilla collection request to a specific VPA provided by the customer, and the customer can pay from that specific VPA only.

Flow

  • Initiate the collect request by passing necessary details, such as the amount and UPI VPA, by triggering the Issue Collect Request API.
  • Once the collection request is triggered:
    • The customer must go to the relevant PSP app and approve the request.
    • Alternatively, most PSP apps also send an SMS to the mobile number mapped to the payer's UPI VPA passed in the request payload.
  • Once the customer approves or rejects the request on the PSP app, Decentro triggers a callback that informs the platform about the transaction's terminal status.
  • Alternatively, the platform can check the payment status using our Get Transaction Status API.

Note: this API is under development and will be rolled out shortly!

Terminal Transaction Status Callback

Decentro triggers this callback whenever a UPI transaction reaches its terminal state. This applies to all incoming transactions and refund requests. The callback will be sent to an endpoint provided by the merchant.

The callback will contain details of the payer, the transaction details, and the transaction status.

Decentro will trigger this callback up to 3 times. The platform is expected to acknowledge the callback.

Link to Terminal Transaction Status Callback/Webhook.

Get Transaction Status

This API provides the transaction status triggered through Generate Payment links/Generate Dynamic QR/ Issue Collect request APIs as an alternative to the transaction status callback.

  • In case multi attempt is enabled, checking the payment status will return the payment link status (SUCCESS, PENDING, EXPIRED).
  • In case multi attempt is disabled, checking the payment status will return the payment link status (SUCCESS, PENDING, FAILED, EXPIRED).

To know the status of each attempt made by the payer, you can either

  1. Refer to the transaction details via the merchant dashboard
  2. Use our Get Transaction status API.

Note: This API cannot be used to view the status of the static QR-based payments.

Link to Get transaction status API.

Validate UPI Handle

This API checks the validity of a UPI ID (Virtual Payment Address) before triggering a collection request or UPI payout.

Flow

Decentro supports 2 flows on its end for validating a VPA.

  • Basic Validation Flow : The platform receives in the response if the UPI handle is valid or not with basic details like name, validation status, etc. Prefer this if the UPI handle is of an individual.
  • Advance Validation Flow: The platform receives in the response if the UPI handle is valid or not with advance details like name, IFSC code, onboarding type, validation status, etc. Prefer this if the UPI handle is of a Merchant.

The platform that intends to validate the UPI handle of the end customer consumes the validated UPI handle API and passes the UPI handle of the concerned individual in the API request payload.

Note: this API is under development and will be rolled out shortly!

Issue UPI Refund

This API can be used to refund any UPI collection transaction. The platform must pass a primary identifier from the original transaction to initiate the refund API. Refunds will always be credited to the source account.

Note:The maximum refund window is 180 calendar days from when the original transaction was successful.

If a refund request fails, you can always re-initiate it. Decentro allows merchants to initiate partial refunds.

Link to the Refund API.

On-Hold/Auto Refund functionality

Platforms can opt for either On-Hold functionality or Auto-Refund functionality to handle scenarios where they want to enable multiple payments against the same request, etc.

Scenarios for On Hold/Auto Refund:

  1. Multiple successful transactions for same payment request: In case there are duplicate successful payments against the same request.
  2. Expired payment issue: In odd cases where the transaction is done AFTER expiration, it will be kept on hold and processed offline.
  3. Technical issue at Bank partner: In cases where the Bank partner fails to communicate an appropriate response for a successful transaction, it will be kept on hold.

These values are propagated via the Terminal Transaction Status Callback when a payment attempt is placed β€˜On-Hold’ or 'Auto-Refunded'.

It is mandatory for platforms that have opted for the "On-Hold" functionality to configure this callback. We recommend that platforms who have opted for the "Auto-Refund" functionality configure this callback to easily address any customer escalations.

Link to Terminal Transaction Status Callback

Releasing/Capturing the On-Hold Funds

This API allows users to release or capture a pending payment attempt. It can only be used by merchants who have configured the β€˜Hold + Release/Capture’ feature for their account.

The platform cannot directly access the refund API. They must use the release capture API for all transactions on hold.

Note: this API is under development and will be rolled out shortly!

Integration

Decentro's collections APIs under the v3 stack are available here Collections v3.

Integration Flow

Below is the integration flow for a platform to consume Decentro's v3 collections stack.

  • The platform receives consumer URN from Decentro upon signing up with Decentro, which needs to be passed when creating a transaction request for collections.
  • The platform has an endpoint configured to handle Terminal Transaction Status Callback/Webhook. This is highly recommended and is done by Decentro before going live to handle transaction status updates.
  • The platform has an endpoint configured to handle Account Balance Callback/Webhook. This is highly recommended and is done by Decentro before going live to handle ledge account balance updates.
  • The platform uses the consumer URN passed by Decentro to undertake collection through one of the below capabilities.
  • The payer authorizes the payment on their device using the relevant UPI MPIN at their end.
  • The platform receives a Terminal Transaction Status Callback/Webhook from Decentro if a transaction reaches a terminal status (SUCCESS, FAILURE, EXPIRED) on the endpoint configured.
  • The platform receives an Account Balance Callback/Webhook from Decentro in case of a SUCCESS transaction if the platform subscribes to it or when the funds are debited to the platform for settlement.
  • The platform can also check the status of a transaction using the Get transaction status API by passing the Decentro ID generated when creating a link/collect request/dynamic QR.
  • The platform can refund a completed transaction through any of the above modes using the Refund API and the transaction will be reversed back to the payer's VPA.

Response Keys

Decentro uses response keys to handle different API and transaction-level scenarios. The platform can use these to message the payer or end consumers for a seamless experience. Response keys vary by API and are covered under the reference pages for each API.

Simulation Data

Overview

The simulation data provides sample data for testing and understanding various scenarios and API behaviors. It offers users a comprehensive set of pre-defined data points to simulate different responses and outcomes, aiding in the thorough exploration and validation of the API's functionality. With this data, developers can efficiently test their integrations and ensure robustness across a range of potential scenarios.

This requires the platform to use standard request payloads to handle scenarios for each API and scenario, as mentioned below.

Generate payment link API & Get Transaction Status API

Below is the test data that platforms can use to test out standard scenarios for Generate payment link. The platform is expected to pass as-is parameters to get the intended scenario.

πŸ“˜

Note - Simulation Data

To test Simulation Staging data for Generate payment link API & Get transaction status API, please use the following API Endpoint -

  1. Payment link - https://staging.api.decentro.tech/v3/payments/upi/link
  2. Get Transaction Status - https://staging.api.decentro.tech/v3/payments/transaction/:decentro_company_urn/status

Flow

  1. Generate a payment link with the 'amount' parameter as either 10, 20, 30, etc depending on the test case being observed.
  2. Obtain the generated link in the generate payment link API response.
  3. After 10 seconds, check the payment's status by using the decentro_txn_id received in the response and input it into the decentro_company_urn field in the Get Transaction Status API.
    1. Note: When the transaction status is SUCCESS or FAILURE, we intentionally delay 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
  4. After another 10 second delay from step 3, the client will receive the terminal status depending on the Amount passed in Step 1.
  5. 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.
  6. Please refer to the table below for Amount v/s transaction status test cases in staging simulation.
AmountTransaction StatusTest case
10UNINITIALIZEDPayment link is not created & payment link status is UNINITIALIZED
20SUCCESSPayment link is created & Transaction status is SUCCESS
30FAILUREPayment link is created & Transaction status is FAILURE
40PENDINGPayment link is created & Transaction status is PENDING