SetuBot
—
–
/

to search

Introducing Setu API playground Check it out ↗

Reading time — 3 minutes

Edit this page ↗

#Third party verification (TPV)

TPV is a service that can be used by a merchant to validate the account from which the customer makes payment. Use cases include paying for mutual funds, stocks etc., where regulation mandates that the customer has to make payment only from their own account.

TPV validates the source account ifsc and account number against the values provided by the merchant.


TPV is an additional service provided by Setu and is enabled only upon request by the merchant.


TPV can be done in two ways—

  • TPV check by Setu
  • TPV check by merchant

#TPV check by Setu

For Setu to carry out TPV, merchant has to provide the ifsc and the account number when creating the payment link.

When customer makes the payment, Setu checks if the source account ifsc and account number match with these values. If they do not match, then the transaction is marked as PAYMENT_FAILED, with reason as TPV check failed and the amount will be refunded in the next settlement cycle.

Payments links created with TPV check are charged for both TPV successful and TPV failed cases.


Creating a payment link with TPV check by Setu
MethodPOST
Path/payment-links
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
{
   "amount":{
      "currencyCode":"INR",
      "value":2000
   },
   "amountExactness":"EXACT",
   "billerBillID":"918147077472",
   "name":"Setu Payment Links Test",
   "validationRules":{
      "sourceAccounts":[
         {
            "number":"9009120939129",
            "ifsc":"SETU0000012"
         }
      ]
   },
   "additionalInfo" : {
      "UUID": "b6b6f173-8649-4b2e-9c22-f78e9195a23e",
      "tags": "electricity"
   }
}
Sample response
{
   "status":200,
   "success":true,
   "data":{
      "name":"Setu Payment Links Test",
      "paymentLink":{
         "shortURL":"https://sandbox.bills.pe/Srmjne3",
         "upiID":"setu868062282653893900@kaypay",
         "upiLink":"upi://pay?pa=setu868062282653893900@kaypay&pn=Setu%20Payment%20Links%20TEst&am=20.00&tr=868062282653893900&tn=Payment%20for%20918147077472&cu=INR&mode=04"
      },
      "platformBillID":"868062282653893900"
   }
}
Sample bill fulfillment notification
{
   "partnerDetails":{
      "appID":"867480814940587229",
      "productInstanceID":"867480814940587229"
   },
   "events":[
      {
         "data":{
            "Reason":"TPV check failed",
            "amountPaid":{
               "currencyCode":"INR",
               "value":2000
            },
            "payerVpa":"saainithil97@icici",
            "sourceAccount":{
               "ifsc":"SETU0000012",
               "number":"9009120939129"
            },
            "status":"PAYMENT_FAILED",
            "transactionId":"6603274139532736",
            "transactionNote":"Payment for 918147077472"
         },
         "timeStamp":1649389668226,
         "type":"BILL_FULFILMENT_STATUS",
         "id":"3f545cad-c179-4360-b0c7-1faad9737571",
         "additionalInfo" : {     // same as values defined when creating the link
            "UUID": "b6b6f173-8649-4b2e-9c22-f78e9195a23e",
            "tags": "electricity"
         },
      }
   ]
}

#TPV check by merchant

In this case, merchant creates the payment link without any source account information.

If TPV is enabled for the merchant, then the source account ifsc and account number are passed on to the merchant, in the bill fulfillment notification. Setu will process the transaction without any checks. Merchant can then carry out the validation on their end and initiate refund as needed, using the Create refund API.

Sample bill fulfillment notification with TPV enabled
{
   "partnerDetails":{
      "appID":"867480814940587229",
      "productInstanceID":"867480814940587229"
   },
   "events":[
      {
         "data":{
            "Reason":"",
            "amountPaid":{
               "currencyCode":"INR",
               "value":2000
            },
            "billerBillID":"918147077472",
            "payerVpa":"saainithil97@icici",
            "platformBillID":"868066686043948303",
            "sourceAccount":{
               "ifsc":"SETU0000012",
               "number":"9009120939129"
            },
            "status":"PAYMENT_SUCCESSFUL",
            "transactionId":"3407080294420161",
            "transactionNote":"Payment for 918147077472"
         },
         "timeStamp":1649389505287,
         "type":"BILL_FULFILMENT_STATUS",
         "id":"481b642f-de67-4cd7-a025-ae3e28329118",
         "additionalInfo" : {   // same as values defined when creating the link
            "UUID": "b6b6f173-8649-4b2e-9c22-f78e9195a23e",
            "tags": "electricity"
         },
      }
   ]
}

Was this page helpful?