—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 3 minutes

Edit this page ↗

#API integration

Integrating Bundled BAV into your application involves creating a verification request and handling the response flow.

#Create a Bundled BAV request

Call the API to generate a verification URL for your customer.

Bundled BAV request created successfully.

Request
POST /api/bundled-bav
{
  "mobileNumber": "9876543210"
}
Response
{
  "requestId": "f4ec6a99-a9a9-4f23-8dea-1da1b285a156",
  "url": "https://dg.setu.co/bundled-bav?payload=1234",
  "success": true,
  "message": "Bundled BAV request created",
  "traceId": "1-1234567890"
}

Note: Store the requestId from this response. You will receive the same requestId in the webhook notification when verification is complete, allowing you to match the webhook to the original request.

#Open URL in webview

Open the returned url in a webview within your application. The customer will see the Bundled BAV interface where they can choose their preferred verification method.

Make sure to handle the webview lifecycle properly to provide a smooth user experience.

#Handle redirect

Once the customer completes the verification process, they will be redirected to the redirectUrl configured in your product settings.

Set up an event listener in your app to detect this redirect and close the webview accordingly.

Example event listener pattern

// Detect when the webview navigates to your redirect URL
webview.onNavigationStateChange = (navState) => {
  if (navState.url.startsWith(YOUR_REDIRECT_URL)) {
    // Close the webview
    closeWebview();
    // Continue with your app flow
    navigateToNextScreen();
  }
};

#Webhook notification

Once the verification is complete, Setu will send the bank account details to your configured webhook endpoint.

The webhook payload will contain the same requestId that you received in the create request response. Use this to match the webhook notification with the original verification request.


Webhook payload

{
  "requestId": "f4ec6a99-a9a9-4f23-8dea-1da1b285a156",
  "data": {
    "accountHolderName": "JOHN DOE",
    "bankAccountNumber": "1234567890",
    "bankAccountIfsc": "ICIC0005573",
    "bankName": "ICICI BANK"
  },
  "bavMethod": "PENNY_DROP",
  "success": true,
  "message": "Bank account verification successful",
  "timestamp": "2026-01-08T12:27:50.697274+00:00"
}

Ensure your webhook endpoint is configured to accept POST requests and can handle the payload structure above.

#Best practices

  1. Handle webhook retries — Make your webhook endpoint idempotent as Setu may retry failed webhook deliveries
  2. Store traceId — Always store the traceId for debugging and support purposes
  3. Handle timeouts — Implement appropriate timeout handling for the webview

Was this page helpful?