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.

POST /api/bundled-bav

{
  "mobileNumber": "9876543210"
}

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

POST /api/bundled-bav

{
  "mobileNumber": "9876543210"
}

{
  "success": false,
  "message": "Bad request - invalid product configuration",
  "traceId": "1-1234567890"
}

POST /api/bundled-bav

{
  "mobileNumber": "9876543210"
}

{
  "success": false,
  "message": "Failed to create request - internal error",
  "traceId": "1-1234567890"
}

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.

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.

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"
}

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