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.

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.

2. 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.

2. 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.
  • Generate payment link API
  • Issue Collect Request
  • Generate Dynamic QR
• 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

Decentro provides a comprehensive simulation testbed to platforms so that their developers or PMs can simulate the real-world scenarios encountered when using payment capabilities.

This requires the platform to use standard request payloads to handle scenarios for each API and scenario. The same is available on each of the API reference pages.

Pre-requisites

Decentro can also simulate the transaction status callback propagation as part of the simulation environment. Please reach out to us at [email protected] to get the IPs and the endpoints whitelisted before testing the same.

Integration

Decentro's simulation testbed doesn't require the user to use different endpoints and the platform can use the same endpoints as the staging environment. The endpoint for each of the APIs are available under the API reference pages.

.