—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 7 minutes

Edit this page ↗

#Refunds

Setu provides access to refund functionality for UPI payments. Refunds can either be auto-initiated by Setu for pre-defined scenarios or can be voluntarily initiated by the merchant.

A refund can take 1 to 9 business days to reflect in the customer's account, once it is initiated. Refunds can be initiated within 170 days from the date of transaction.


Refunds are initiated in batch, along with bill settlements done to the merchant. If the amount to be refunded is already settled to the merchant in a previous settlement, it is adjusted in the present settlement.

#Types of refunds

Refunds are of three types, based on the reason for initiation—

  • Setu initiated refunds — Setu automatically refunds a transaction in cases where the transaction is not properly routed through the UPI eco-system and cannot be reconciled. Setu also initiates refunds automatically when amount exactness validation rules set for the payment link, fail.
  • Merchant initiated refunds — Merchant can request for a refund for one or more transactions. Reasons could include return of goods and services and more.
  • Third party verification (TPV) refunds — If the account used by the customer for making payment does not match what the merchant is expecting, a refund can be initiated. TPV is enabled by Setu only upon request from the merchant.

#Setu initiated refunds

When a transaction is processed through the UPI eco-system, data flows through many points. Any errors in this path can result in a situation where Setu cannot reconcile the transaction. Hence, Setu automatically refunds these transactions to the customer's source VPA. Some of these situations include—

  • Missing orderID
  • Incorrect orderID
  • Missed notification from bank

Setu also initiates refunds in these situations—

Setu initiated refund process

For transactions that come under Setu initiated refunds, the bill fulfillment notification for that particular transaction will have PAYMENT_FAILED as the status.

Setu will later notify the merchant about the refund initiation, in the next settlement cycle. See refund notifications.

In cases where the orderID is missing or invalid, Setu cannot identify the merchant and hence will not provide any refund notification to the merchant. However, the refund will still be processed to the customer's VPA.

Setu initiated refunds are credited to the customer's source VPA in 1 to 9 business days — no intervention from the merchant is needed.


#Merchant initiated refunds

A merchant can choose to refund a payment to the customer after the payment is complete or settled. Refunds have to be initiated within 60 days from the date of transaction.

Create and check refund status with the following APIs.

#Create refund API

Create a refund request for one or more transactions.

MethodPOST
Path/refund/batch
HeaderX-Setu-Product-Instance-ID

Authorization: Bearer <insert_token_here>. Generate this token using OAuth or JWT.

Content-Type—will be application/json
Sample request (when original transaction has no split instructions)
{
    "refunds": [
        {
            "seqNo": 1,
            "identifier": "1099309092570138096",
            "identifierType": "BILL_ID",
            "refundType": "FULL"
        },
        {
            "seqNo": 2,
            "identifier": "1099309493419771390",
            "identifierType": "BILL_ID",
            "refundType": "PARTIAL",
            "refundAmount": {
                "currencyCode": "INR",
                "value": 1500
            }
        }
    ]
}
Sample request (when original transaction has split instructions)
{
    "refunds": [
        {
            "seqNo": 1,
            "identifier": "896458251304961390",
            "identifierType": "BILL_ID",
            "refundType": "FULL",
            "deductions": [
                {
                    "account": {
                        "id": "Biller-External-001",
                        "ifsc": "KKBK0000001",
                        "name": "External-biller-Acc-1"
                    },
                    "split": {
                        "unit": "INR",
                        "value": 20000
                    }
                },
                {
                    "account": {
                        "id": "Biller-External-002",
                        "ifsc": "KKBK0000001",
                        "name": "External-biller-Acc-2"
                    },
                    "split": {
                        "unit": "INR",
                        "value": 10000
                    }
                }
            ]
        }
    ]
}
Sample response
{
    "status": 200,
    "success": true,
    "data": {
        "batchID": "ca1l9e1bnsesi098pbn0",
        "refunds": [
            {
                "amount": {
                    "currencyCode": "INR",
                    "value": 20000
                },
                "billID": "896458251304961389",
                "deductions": [
                    {
                        "account": {
                            "id": "Biller-External-001",
                            "ifsc": "KKBK0000001",
                            "name": "External-biller-Acc-1"
                        },
                        "split": {
                            "unit": "INR",
                            "value": 20000
                        }
                    }
                ],
                "id": "896458511922234749",
                "status": "Created",
                "transactionRefID": "8127920116918371",
                "seqNo": 1,
                "success": true
            },
            {
                "amount": {
                    "currencyCode": "INR",
                    "value": 5000
                },
                "billID": "896458450802836853",
                "deductions": [
                    {
                        "account": {
                            "id": "Biller-External-001",
                            "ifsc": "KKBK0000001",
                            "name": "External-biller-Acc-1"
                        },
                        "split": {
                            "unit": "INR",
                            "value": 5000
                        }
                    }
                ],
                "id": "896458511980955006",
                "status": "Created",
                "transactionRefID": "6004660259904990",
                "seqNo": 2,
                "success": true
            }
        ]
    }
}

The API returns a batchID for the refund, which can be used to check the status of the refund.

#Check refund batch status API

Check status of refunds created against a particular batchID.

MethodGET
Path/refund/batch/:batchID
HeaderX-Setu-Product-Instance-ID

Authorization: Bearer <insert_token_here>. Generate this token using OAuth or JWT.

Content-Type—will be application/json
Sample response
{
    "status": 200,
    "success": true,
    "data": {
        "refunds": [
            {
                "amount": {
                    "currencyCode": "INR",
                    "value": 1500
                },
                "billID": "1099299575895688621",
                "createdAt": "2023-02-21T04:44:10.082Z",
                "deductions": [
                    {
                        "account": {
                            "id": "50100221813167",
                            "ifsc": "HDFC0000839",
                            "name": "Santosh-Test"
                        },
                        "split": {
                            "unit": "INR",
                            "value": 1500
                        }
                    }
                ],
                "id": "1099299900383823287",
                "initiatedAt": "2023-02-21T04:44:50.461Z",
                "status": "Initiated", // ENUM — Created, Pending, Initiated
                "transactionRefID": "2092666374742383",
                "type": "MerchantInitiated"
            }
        ]
    }
}
What are the different types of refund statuses?

Created: This is when the merchant initiates a refund request via APIs or through The Bridge (Setu dashboard). The refund or its processing has not taken place at this point.

Initiated: This is when the refund request has been intimated to the banking partner and begins processing the refund. This is the terminal status of a refund, as NPCI does not share information about when a refund hits the customer’s bank account.

Pending: This status is implied in case the refunds are awaiting to be reconciled or have completed reconciliation, yet not processed due to one of the following reasons:

  • Insufficient funds: Refunds requested by a merchant are adjusted from the settlement amount to the merchant's account. But if the amount for a particular refund request cannot be adjusted due to insufficient settlement amount, the refund remains in a Pending state.

    Example: If the total settlement amount for the day for Merchant X is ₹850 and the merchant has created 10 refunds of ₹100 each totalling ₹1000 in the same duration, only the first 8 will get refunded and move to an initiated state. The callback notification sent to the merchant will contain the first 8 refunds in the initiated block and the remaining in the pending block.

  • No Active Transactions: A requested refund will remain in a Pending state if there are no active transactions (and thus settlements to the merchant's account) from which the refund amount can be deducted and sent back to the customer.

    Example: Merchant Y has not transacted for 1 or more days and has created Refund requests. Since there are no active transactions, the refunds would remain in Pending status with the reason No Active Transactions

Rejected: This status is used only in the exceptional scenario where a merchant wants a previously requested refund not to be processed and requests the Setu team to reject the request. This request is currently to be raised offline.

#Check individual refund status API

Check status of a specific refund with the refund id.

MethodGET
Path/refund/:refundId
refundId is the id provided in the refunds array of Create refund API
HeaderX-Setu-Product-Instance-ID

Authorization: Bearer <insert_token_here>. Generate this token using OAuth or JWT.

Content-Type—will be application/json
Sample response
{
    "status": 200,
    "success": true,
    "data": {
        "amount": {
            "currencyCode": "INR",
            "value": 1500
        },
        "billID": "1099299575895688621",
        "createdAt": "2023-02-21T04:44:10.082Z",
        "deductions": [
            {
                "account": {
                    "id": "50100221813167",
                    "ifsc": "HDFC0000839",
                    "name": "Santosh-Test"
                },
                "split": {
                    "unit": "INR",
                    "value": 1500
                }
            }
        ],
        "id": "1099299900383823287",
        "initiatedAt": "2023-02-21T04:44:50.461Z",
        "status": "Initiated", // ENUM — Created, Pending, Initiated
        "transactionRefID": "2092666374742383",
        "type": "MerchantInitiated"
    }
}

#Refund notifications

Check out refund notifications ↗

Was this page helpful?