Setu

https://docs.setu.co
Admin
Setu is a fintech API platform providing services for financial data access, KYC, eSign, bill...
Tokens:452,630
Snippets:2,334
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example LIST response structure

Source: https://docs.setu.co/payments/billpay/api-integration/paying-bills/multi-bill-processing

Example LIST response structure showing multiple bills with billerSelectionType MULTIPLE.

```json
{
  "data": {
    "refId": "FETCH_REF_123",
    "billerResponseType": "LIST",
    "billerSelectionType": "MULTIPLE",
    "bills": [
      { "billNumber": "BILL_001", "amount": 50000 },
      { "billNumber": "BILL_002", "amount": 75000 }
    ]
  }
}
```

--------------------------------

### Signature example with input and secret

Source: https://docs.setu.co/payments/bbps/resources/jwt

Shows an example of the input string, secret, and resulting HMAC SHA256 signature. The signature is used to verify the sender of the JWT.

```text
Input string   : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI4ZjQ3ZTQxYy00Njg0LTRhZjEtYjFiOC0yNDZjODMxMTIwMzMiLCJpYXQiOjE1NzI0OTMzNTYsImp0aSI6ImM1MzQ0N2UzLTk5M2EtNDRhZS05Yzc4LTMxZjQ1YzNjMDgyZSJ9
Secret         : 7c2e036c-908f-48ba-abe3-cd8745a6fa99
HA256 Signaure : xfYii9lfWMHtMBgjK5U6NFN_6_Q9jw8UMQu8Jnvftbs
```

--------------------------------

### List Billers API - Response Example with Removed Fields

Source: https://docs.setu.co/payments/billpay/api-integration/v2-migration

Example response from the List Billers API after migration. The `plans` and `tags` fields have been removed from the response body.

```json
{
    "data": {
        "billers": [
            {
                "categoryName": "Loan Repayment",
                "coverage": "IND",
                "createdAt": "2021-04-08T00:00:00.000+05:30",
                "customerParams": [
                    {
                        "dataType": "ALPHANUMERIC",
                        "maxLength": 8,
                        "minLength": 8,
                        "optional": false,
                        "paramName": "Application ID",
                        "regex": "^[a-zA-Z0-9]+$",
                        "values": null,
                        "visibility": false
                    }
                ],
                "customerParamsGroups": [],
                "exactness": "Any",
                "fetchApiType": "BILL_FETCH",
                "id": "AADH00000NATPT",
                "logo": "https://logo.s3.amazonaws.com/AADH00000NATPT.png",
                "modifiedAt": "2023-07-19T12:00:01.086+05:30",
                "name": "Badhar Housing Finance Limited",
                "payWithoutFetchAllowed": false,
                "paymentChannels": [
                    {
                        "maxLimit": 99999900,
                        "minLimit": 100,
                        "paymentChannel": "INT",
                        "supportsPendingStatus": false
                    }
                ],
                "paymentModes": [
                    {
                        "maxLimit": null,
                        "minLimit": 1,
                        "paymentMode": "Internet Banking",
                        "supportsPendingStatus": false
                    }
                ],
-                "plans": [],
-                "tags": "",
                "supportsPendingStatus": false
            }
    }
}
```

--------------------------------

### Insights started notification example

Source: https://docs.setu.co/data/signal-iq/aa-flow

Example schema for the insights job started stage. Includes reportId and datablockId fields.

```json
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_STARTED",
    "consentId": "9dee34fe-8449-4f80-914e-b9725f3585cd",
    "reportId": "7f3e4d5c-1111-2222-3333-444455556666",
    "datablockId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

--------------------------------

### Initialize WKWebviewDownloadHelper

Source: https://docs.setu.co/payments/billpay/pre-built-screens/custom-payment/iOS

Configures the download helper in viewDidLoad to handle PDF files and register the observer.

```swift
override func viewDidLoad() {
  super.viewDidLoad()
  let mimeTypes = [MimeType(type: "pdf", fileExtension: "pdf")]
  helper = WKWebviewDownloadHelper(webView: webView, mimeTypes: mimeTypes, delegate: self)
  webView.configuration.userContentController.add(self, name: "ios_observer")
}
```

--------------------------------

### Example Request Body Parameters

Source: https://docs.setu.co/data/bav/reverse-penny-drop/api-integration

Shows the structure for optional redirection configuration and additional data fields in the request body.

```json
        "additionalData": {
            "customField": "value"
        },
        "redirectionConfig": {
            "redirectUrl": "https://example.com",
            "timeout": 30
        }
    
```

--------------------------------

### Get FIPs by Status API - Request

Source: https://docs.setu.co/data/account-aggregator/api-integration/fip-apis

HTTP GET request to retrieve FIPs filtered by status. The example uses status=ACTIVE.

```http
 GET /v2/fips?status=ACTIVE 
```

--------------------------------

### Get FIP by ID API Success Response

Source: https://docs.setu.co/data/account-aggregator/api-integration/fip-apis

Example success response for the Get FIP by ID API. Contains a single FIP object in the data array and a traceId.

```json
{
    "data": [
        {
            "name": "Axis Bank",
            "fipId": "AXIS001",
            "fiTypes": [
                "DEPOSIT"
            ],
            "institutionType": "BANK",
            "status": "ACTIVE",
            "consentConversionRate": 93.95, // Aggregate of all AA's
            "dataFetchSuccessRate": 97.55,
            "aaWiseSuccessRate": [
                {
                    "consentConversionRate": 95.35,
                    "dataFetchSuccessRate": 98.55,
                    "aa": "onemoney"
                },
                {
                    "consentConversionRate": 92.55,
                    "dataFetchSuccessRate": 96.55,
                    "aa": "anumati"
                }
            ]
        }
    ],
    "traceId": "1-66ff79c7-46029a1f1aaa59083489fd46"
}
```

--------------------------------

### Main Method Demonstrating Hybrid Encryption Workflow

Source: https://docs.setu.co/data/kyc/encryption

Shows a complete workflow: defines RSA keys and sample data, encrypts the data, prints the encrypted response, then decrypts and prints the decrypted data. Replace the placeholder keys with actual values.

```java
public static void main(String[] args) {
	String privateKey = "<YOUR_RSA_PRIVATE_KEY>";
	String publicKey = "<YOUR_RSA_PUBLIC_KEY>";
	String data = "{\"ifsc\":\"ABCD0123456\",\"accountNumber\":\"1234567890\",\"narration\":\"test transaction\",\"matchKey\":\"gaurav\"}";
	Map<String, String> encryptedResponse = encrypt(publicKey, data);
	System.out.println("Encrypted Response: " + encryptedResponse);
	String decryptedData = decrypt(privateKey, encryptedResponse.get("encrypted_key"), encryptedResponse.get("encrypted_data"));
	System.out.println("Decrypted Data: " + decryptedData);
}
```

--------------------------------

### Create payment link with TPV check by Setu - Sample request

Source: https://docs.setu.co/payments/upi-deeplinks/third-party-verification

POST /payment-links request body with validationRules.sourceAccounts containing the expected IFSC and account number. Requires X-Setu-Product-Instance-ID header and Authorization Bearer token. TPV is enabled only upon request.

```json
{
   "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"
   }
}
```

--------------------------------

### Tiered CCF example with multiple slabs

Source: https://docs.setu.co/payments/billpay/api-integration/paying-bills/customer-convenience-fee

Example of tiered CCF where interchangeFeeDetailsV2 contains multiple slabs. Values are illustrative; use the slab where the bill amount in paise falls between tranAmtRangeMin and tranAmtRangeMax (inclusive) to get the flatFee and percentFee.

```json
{
  "feeCode": "CCF1",
  "feeDesc": "Customer_Convenience_Fee",
  "feeDirection": "C2B",
  "interchangeFeeDetails": {
    "effctvFrom": "2025-11-07",
    "effctvTo": "",
    "flatFee": 590,
    "percentFee": 0,
    "tranAmtRangeMax": 200000,
    "tranAmtRangeMin": 1
  },
  "interchangeFeeDetailsV2": [
    {
      "effctvFrom": "2025-11-07",
      "effctvTo": "",
      "flatFee": 590,
      "percentFee": 0,
      "tranAmtRangeMax": 200000,
      "tranAmtRangeMin": 1
    },
    {
      "effctvFrom": "2025-11-07",
      "effctvTo": "",
      "flatFee": 1180,
      "percentFee": 0,
      "tranAmtRangeMax": 500000,
      "tranAmtRangeMin": 200001
    }
  ]
}
```

--------------------------------

### Enhanced FIP List API with Health Metrics - Request

Source: https://docs.setu.co/data/account-aggregator/api-integration/fip-apis

HTTP GET request to retrieve the enhanced FIP list with health metrics. The example uses expanded=true.

```http
 GET /v2/fips?expanded=true 
```

--------------------------------

### Send your first eSign request

Source: https://docs.setu.co/

Example request to the eSign document endpoint.

```http
POST /api/v1/documents/esign
{ signers: [...],
  redirectUrl: "..." }
```

--------------------------------

### Sample paymentDetails object

Source: https://docs.setu.co/payments/umap/payments/tpv/life-cycle

An example of the paymentDetails object returned when a payment is accepted successfully.

```json
{
      "paymentDetails": {
         "customerAccountType": "SAVINGS",
         "customerVpa": "ram@icici",
         "paymentId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
         "paymentStatus": "success",
         "rrn": "124068997913",
         "txnId": "SETmBZkQOV0M7wyyP1V4PIFhRSzW5eSjmYI"
      }
}
```

--------------------------------

### Check collect request status - Sample response

Source: https://docs.setu.co/payments/umap/payments/collect/create-collect-request

Example response from the GET /v1/merchants/collect/{id} endpoint, including optional reason object with NPCI error details when the request fails.

```json
{
  "amount": 10000,
  "closedAt": "2023-09-04T12:08:20+0530",
  "createdAt": "2023-09-04T12:08:20+0530",
  "currency": "INR",
  "customerVpa": "ram@okhdfc",
  "expireAfter": 2,
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "merchantId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "merchantReferenceId": "1240689979139556557",
  "merchantVpa": "fastestupi@pineaxis",
  "metadata": {
    "InvoiceNumber": "INV-21-12-009"
  },
  "productConfigId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "reason": {
    "code": "unable-to-fulfill-request",
    "desc": "unable-to-fulfill-request",
    "npciErrCode": "YG",
    "npciErrDesc": "MERCHANT ERROR (PAYEE PSP)",
    "npciRespCode": "YG",
    "npciRespDesc": "MERCHANT ERROR (PAYEE PSP)"
  },
  "refId": "1240689979139556558",
  "status": "active",
  "transactionNote": "testcollect"
}
```

--------------------------------

### Bill Fetch Response

Source: https://docs.setu.co/payments/billpay/api-integration/paying-bills/quickstart

Example response from a bill fetch request. Contains a refId, status, and an array of bills with amount, customerName, dueDate, and billNumber. See the Objects guide for the complete bill response.

```json
{
  "data": {
    "refId": "FETCH_REF_123",
    "status": "Success",
    "bills": [
      {
        "amount": 150000,
        "customerName": "John Doe",
        "dueDate": "2024-01-15",
        "billNumber": "BILL123"
        // See Objects guide for complete bill response: /payments/billpay/api-integration/objects#fetched-bill
      }
    ]
  }
}
```

--------------------------------

### Create payment link with TPV check by Setu - Sample response

Source: https://docs.setu.co/payments/upi-deeplinks/third-party-verification

Successful response from POST /payment-links, containing the payment link details and platformBillID. The shortURL and upiLink are used for payment.

```json
{
   "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"
   }
}
```

--------------------------------

### Notification Payload Examples

Source: https://docs.setu.co/data/signal-iq/pdf-flow

Examples of every schema for each status in the AUTO_DI_STATUS notification flow.

```APIDOC
## Notification Payload Examples

### Description
Examples of every schema for each status in the AUTO_DI_STATUS notification flow.

### PDF_PARSE_FAILED
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "PDF_PARSE_FAILED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "errorCode": "BSP-105",
    "errorMessage": "Unable to detect bank statement format. Please verify the bank name and resubmit."
  }
}

### PDF_FRAUD_DETECTED
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "PDF_FRAUD_DETECTED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "fraudSignals": {
      "overall": "IRREGULARITY_DETECTED",
      "checks": [],
      "vendorScore": null
    }
  }
}

### STATEMENT_VALIDATION_FAILED
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "STATEMENT_VALIDATION_FAILED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "statementValidation": {
      "status": "FAIL",
      "issues": []
    }
  }
}

### PDF_PARSE_SUCCESS
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "PDF_PARSE_SUCCESS",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af"
  }
}

### FI_DATA_BLOCK_CREATION_SUCCESS
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "FI_DATA_BLOCK_CREATION_SUCCESS",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "dataIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }
}

### INSIGHTS_CREATION_STARTED
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_STARTED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "reportId": "7f3e4d5c-1111-2222-3333-444455556666"
  }
}

### INSIGHTS_CREATION_SUCCESSFUL
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_SUCCESSFUL",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "reportId": "7f3e4d5c-1111-2222-3333-444455556666"
  }
}

### INSIGHTS_CREATION_FAILED
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_FAILED",
    "uploadId": "fb12d1a2-1e5c-4c63-aa54-d5f1d2ec19af",
    "errorCode": "BSP-501",
    "errorMessage": "Insights computation failed. Please contact support with the uploadId."
  }
}
```

--------------------------------

### Fetch response with paymentOptions

Source: https://docs.setu.co/payments/billpay/api-integration/paying-bills/bill-payment-options

Example of a bill fetch response containing a paymentOptions array with alternative payment amounts. All amounts are in paise.

```json
{
  "data": {
    "refId": "FETCH_REF_123",
    "bills": [
      {
        "amount": 200000,
        "billDate": "2024-12-15",
        "dueDate": "2024-12-30",
        "additionalInfo": [
          { "name": "Early Payment Date", "value": "2024-12-20" }
        ],
        "paymentOptions": [
          { "name": "Early Payment Amount", "amount": 195000 },
          { "name": "Late Payment Amount", "amount": 205000 }
        ]
      }
    ]
  }
}
```

--------------------------------

### Implement WebView in SwiftUI

Source: https://docs.setu.co/payments/billpay/pre-built-screens/quickstart/iOS

This code demonstrates how to set up a WKWebView within a SwiftUI view, including navigation handling and a custom back button.

```swift
import SwiftUI
import WebKit
struct ContentView: View {
    var body: some View {
        NavigationView {
            WebView(urlString: "https://billpay.setu.co/1234") // Replace with the actual URL
                .navigationBarItems(leading: WebViewBackButton())
                .onAppear {
                    NotificationCenter.default.addObserver(forName: Notification.Name("GoBack"), object: nil, queue: .main) { _ in
                        WebViewCoordinator.shared.goBack()
                    }
                }
        }
    }
}
struct WebViewBackButton: View {
    var body: some View {
        Button(action: {
            NotificationCenter.default.post(name: Notification.Name("GoBack"), object: nil)
        }) {
            Text(Image(systemName: "chevron.left"))
        }
    }
}
class WebViewCoordinator: NSObject, ObservableObject, WKNavigationDelegate, WKScriptMessageHandler {
    static let shared = WebViewCoordinator()
    var webView: WKWebView?
    func goBack() {
        webView?.goBack()
    }
    // Handle navigation actions, including opening "upi" or "phonepe" URLs
    func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
        if let url = navigationAction.request.url, ["upi", "phonepe"].contains(where: { url.absoluteString.contains($0) }) {
            UIApplication.shared.open(url)
            decisionHandler(.cancel)
        } else {
            decisionHandler(.allow)
        }
    }
}
struct WebView: UIViewRepresentable {
    let urlString: String
    @EnvironmentObject var coordinator: WebViewCoordinator
    func makeUIView(context: Context) -> WKWebView {
        let webView = WKWebView()
        webView.navigationDelegate = context.coordinator
        // Register script message handler
        webView.configuration.userContentController.add(context.coordinator, name: "ios_observer")
        context.coordinator.webView = webView
        return webView
    }
    func updateUIView(_ uiView: WKWebView, context: Context) {
        if let url = URL(string: urlString) {
            uiView.load(URLRequest(url: url))
        }
    }
    func makeCoordinator() -> WebViewCoordinator {
        WebViewCoordinator.shared
    }
}
#if DEBUG
struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView().environmentObject(WebViewCoordinator.shared)
    }
}
#endif
```

--------------------------------

### Get Payment Status Request

Source: https://docs.setu.co/payments/billpay/pre-built-screens/custom-payment/apis

Request body for the get payment status API.

```json
{
  "orderId": "COUWLje9V7wWs9N3w"
}

```

--------------------------------

### Insights failed notification example

Source: https://docs.setu.co/data/signal-iq/aa-flow

Example schema for the insights failed stage. This status is a terminal failure.

```json
{
  "type": "AUTO_DI_STATUS",
  "data": {
    "status": "INSIGHTS_CREATION_FAILED",
    "consentId": "9dee34fe-8449-4f80-914e-b9725f3585cd",
    "reportId": "7f3e4d5c-1111-2222-3333-444455556666",
    "datablockId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

--------------------------------

### Accept your first UPI payment

Source: https://docs.setu.co/

Example request to the UPI payments endpoint.

```http
POST /api/v2/payments
{ amountInPaise: 24900,
  billerBillID: "INV-9182" }
```

--------------------------------

### Implement WKWebViewDownloadHelperDelegate

Source: https://docs.setu.co/payments/billpay/pre-built-screens/custom-payment/iOS

Handles the file download completion by presenting a UIActivityViewController to the user.

```swift
extension WebViewController: WKWebViewDownloadHelperDelegate {
  func fileDownloadedAtURL(url: URL) {
    DispatchQueue.main.async {
      let activityVC = UIActivityViewController(activityItems: [url], applicationActivities: nil)
      activityVC.popoverPresentationController?.sourceView = self.view
      activityVC.popoverPresentationController?.sourceRect = self.view.frame
      activityVC.popoverPresentationController?.barButtonItem = self.navigationItem.rightBarButtonItem
      self.present(activityVC, animated: true, completion: nil)
    }
  }
}
```

--------------------------------

### Get FIP by ID API Request

Source: https://docs.setu.co/data/account-aggregator/api-integration/fip-apis

HTTP GET request to retrieve a specific FIP by its ID.

```http
GET /v2/fips/:id
```

--------------------------------

### Fetch your first AA consent

Source: https://docs.setu.co/

Example request to the Account Aggregator consent endpoint.

```http
POST /api/v2/consents
{ fiTypes: ["DEPOSIT"],
  purpose: "UNDERWRITING" }
```
Tokens:
Raw