Collections

This module allows businesses to collect funds from their customer or partners

This collection of APIs enables you to collect money via UPI (Unified Payments Interface) from your customers or enable your partner businesses/SMEs to do the same. We support multiple methods like UPI QR codes, payment links, and sending direct collection requests to the designated UPI ID.

UPI Flows

Decentro supports multiple types of collection flows using UPI.

  • Collection Request: This is a flow where the customer or the platform knows the UPI handle from which collection is to be done. The customer needs to navigate to the app against which the handle is registered and approve the request
  • Payment Link: This is a flow where the customer or the platform generates a fixed or variable amount UPI link that can be paid through any of the PSP apps on the customer's mobile through a generic UPI payment link or UPI deep links for PSP apps
  • QR Code: This is a flow where the platform can create a UPI collection QR code and the payer can pay from any UPI of their choice. This is a flow recommended for flows on laptop/desktop or for offline flows like merchant transactions, etc
  • Push Transaction: This is a flow where the platform generates a dynamic handle to which a customer pays using their preferred PSP app
  • UPI Mandates: This is a recurring mandate flow where the customer pre-authorizes the debit amount and frequency and debits happen as per the schedule. More details can be found here

Points to Note:

  • If you are looking to provide complete flexibility to customers in terms of payment experience without taking the customer outside the app, a payment link is recommended
  • If you are asking the customer for a specific UPI handle (VPA) from which payment is to be done, then a collection request is recommended
  • If you are comfortable with the customer going outside your platform to approve the request and you want to track transactions against a specific customer, push transaction is recommended

πŸ“˜

Collections SDKs

Decentro has now released UPI collection SDKs that support multiple languages like React.js, React and Android that platforms can use to embed payment flows on their app/site without the effort of end-to-end integration. Please contact us at [email protected] if you are an existing customer of Decentro or signup here for quick access!

Issue Collect Request

Collection requests powered by Decentro for platforms to request money to specific UPI ID.

Send a payment collection request to a specific UPI ID (for example - abcd@bank).

  • collect 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:

  • Once the collection request is triggered, the customer needs to go to the relevant PSP app and approve the request.
  • Alternatively, most PSP apps send an SMS to the registered number for the same and the customer can authorize the same on the PSP app.
  • Once the customer approves or rejects the request on the PSP app, Decentro triggers a callback that informs the client about the terminal status of the transaction. An account balance callback is also triggered simultaneously to update the platform about the updated balance in the account post the transaction is successful.
  • The platform can check the status of the request as well using the reference ID generated from the collection request

Link to the Issue Collect Request

Generate UPI Payment Link

Decentro supports multiple types of payment links.

  • Generic UPI Link: This is a vanilla payment link that can be used by the customer to pay from any PSP app. This typically opens up all the UPI apps available on the mobile if found and the customer can choose the app to pay from
  • UPI QR code: This is a vanilla QR code that can be used by the customer to scan and pay from any PSP app of their choice
  • UPI Deep-links: This is a variation of the payment link where Decentro provides protocols (deep links) for popular PSP apps

Flow:

  • Once the payment link is generated, the customer can choose the preferred PSP app and approve the request.
  • Once the customer approves or rejects the request on the PSP app, Decentro triggers an account balance callback
  • The platform can check the status of the request as well using the reference ID generated from the collection request

Link to Generate UPI Payment Link

{
    "reference_id": "Reference_id_1234_5678",
    "payee_account": "4625xxxxxxxxx55860",
    "amount": 100.0,
    "purpose_message": "test",
    "generate_qr": 1,
    "expiry_time": 15,
    "customized_qr_with_logo": 0,
    "generate_uri": 1
}
{
    "decentroTxnId": "28E176AB3737443BB1288B2A39D09000",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "Payment Link created Successfully.",
    "data": {
        "generatedLink": "https://decf.in/pay/qr5nw3hjud",
        "transactionId": "28E176AB3737443BB1288B2A39D09000",
        "transactionStatus": "PENDING"
    },
    "responseKey": "success_payment_link_created"
}

Check Payment Status

This API can be used to get the status of the collection triggered using the Payment link/Collection request.

Note: This cannot be used against UPI push or QR code-based transactions.

Link to Check Payment Status

{
    "decentroTxnId": "5148B3xxxxxxxxx9B484DAECA",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "UPI Transaction Status processed successfully",
    "data": {
        "transactionStatus": "SUCCESS",
        "transactionStatusDescription": "SUCCESS",
        "bankReferenceNumber": "35xxxxxx6952",
        "npciTxnId": "PTM22xxxxxxxxxxxxa1ad9f2f03f294"
    },
    "responseKey": "success_transaction_status_successful"
}
{
    "decentroTxnId": "8EF449Fxxxxxxxxx7F76B304",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "UPI Transaction Status processed successfully",
    "data": {
        "transactionStatus": "FAILED",
        "transactionStatusDescription": "Transaction failed",
        "bankReferenceNumber": "3xxxxxx0467",
        "npciTxnId": "ICI781xxxxxxxxx143303aa9d533",
        "errorKey": "error_at_remitter_bank"
    },
    "responseKey": "success_transaction_status_failure"
}
{
    "decentroTxnId": "9D6D481xxxxxxxxxxxxFD8B4FC2",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "UPI Transaction Status processed successfully",
    "data": {
        "transactionStatus": "PENDING",
        "bankReferenceNumber": "NA",
        "npciTxnId": "NA"
    },
    "responseKey": "success_transaction_status_pending"
}
{
    "decentroTxnId": "5296XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "FAILURE",
    "responseCode": "E00009",
    "message": "This transaction was not found in our system. If there was any debit or credit, it would have already been reversed. Please retry the corresponding transaction.",
    "responseKey": "error_no_transaction_found"
}

Validate UPI Handle

This API is used to check if a particular UPI-ID (Virtual Payment Address) is valid or not. Decentro recommends platforms use this before triggering a collection request or even doing UPI payouts.

Link to the validate UPI Handle (VPA)

πŸ‘¨β€πŸ’»

Simulation Data

Validate VPA scenarios can be simulated basis the test data here.

{
    "reference_id": "0000-0000-0000-0001",
    "upi_id" : "<upi-id>",
    "type": "basic"
}
{
    "decentroTxnId": "9BF9xxxxxxxxxxxxx9CB58036B",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "UPI-ID (Virtual Payment Address) validation processed successfully",
    "data": {
        "upiId": "<UPI-ID>",
        "name": "ABC",
        "status": "VALID",
        "statusDescription": "Transaction Successful"
    },
    "responseKey": "success_UPI_id_valid"
}
{
    "reference_id": "0000-0000-0000-0001",
    "upi_id" : "<upi-id>",
    "type": "advance"
}
{
    "decentro_txn_id": "FEA0Exxxxxxxxxxxxxx4EEF4",
    "status": "SUCCESS",
    "response_code": "S00000",
    "message": "UPI-ID (Virtual Payment Address) validation processed successfully",
    "data": {
        "upi_id": "<upi-id>",
        "name": "ABC",
        "status": "VALID",
        "status_description": "Success",
        "merchant_code": "0xx0",
        "merchant_ifsc": "RAxxxx00000",
        "merchant_account_type": "SAVINGS"
    },
    "responseKey": "success_UPI_id_valid"
}
{
    "reference_id": "0000-0000-0000-0001",
    "upi_id" : "<upi-id>",
    "type": "advance"
}
{
  "decentro_txn_id": "23C895xxxxxxxxxxxxxxxx14CCE89C",
  "status": "SUCCESS",
  "response_code": "S00000",
  "message": "UPI-ID (Virtual Payment Address) validation processed successfully",
  "data": {
    "upi_id": "<upi-id>",
    "name": "ABC",
    "status": "VALID",
    "status_description": "Success",
    "merchant_code": "5xX6",
    "merchant_ifsc": "IDxxxxxxD532",
    "merchant_account_type": "CURRENT",
    "merchant_legal_name": "ABC",
    "merchant_type": "SMALL",
    "merchant_onboarding_type": "BANK",
    "merchant_genre": "OFFLINE"
  },
  "responseKey": "success_UPI_id_valid"
}
{
    "reference_id": "0000-0000-0000-0001",
    "upi_id" : "<invalid-upi-id>",
    "type": "advance"
}
{
  "decentro_txn_id": "D056DB219AFE4983949F396D0F30970F",
  "status": "SUCCESS",
  "response_code": "S00000",
  "message": "UPI-ID (Virtual Payment Address) validation processed successfully",
  "data": {
    "upi_id": "<upi-id>",
    "status": "INVALID",
    "status_description": "VPA is invalid"
  },
  "responseKey": "success_UPI_id_valid"
}
{
    "reference_id": "0000-0000-0000-0001",
    "upi_id" : "ABC%^l:$",
    "type": "advance"
}
{
    "decentroTxnId": "18B305E13B594B1CABAE5C7B2CB1293D",
    "status": "FAILURE",
    "responseCode": "E00009",
    "message": "UPI-ID (Virtual Payment Address) is not in a valid format. Please try again with a valid UPI-ID",
    "responseKey": "error_invalid_UPI_id_format"
}

Issue UPI Refund

This API can be used to refund an initiated UPI collection like a collection request and payment link. The account from which the debit happened will receive the credit as well.

Link to the Issue UPI Refund

Callback

Decentro triggers callbacks to the pre-configured endpoints for all kinds of transactions like UPI deep links, UPI generic payment links, UPI QR code transactions, Collection requests and UPI Push transactions.

Details on the callbacks can be found here