Skip to content

Commit cea289c

Browse files
abhijha-setuabhijha-setu
authored
Merge pull request #398 from SetuHQ/feat/bundled-bav-docs-staging
docs: Add Bundled BAV docs for staging
2 parents 0093e48 + b7b7d20 commit cea289c

5 files changed

Lines changed: 610 additions & 0 deletions

File tree

‎content/data/bav/bundled-bav.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
sidebar_title: Bundled BAV
3+
page_title: Bundled Bank Account Verification
4+
order: 2
5+
visible_in_sidebar: true
6+
---

‎content/data/bav/bundled-bav/api-integration.mdx‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
sidebar_title: API integration
3+
page_title: Bundled BAV API integration
4+
order: 2
5+
visible_in_sidebar: true
6+
---
7+
8+
## API integration
9+
10+
Integrating Bundled BAV into your application involves creating a verification request and handling the response flow.
11+
12+
<hr class="tertiary" />
13+
14+
### Create a Bundled BAV request
15+
16+
Call the API to generate a verification URL for your customer.
17+
18+
<Row>
19+
<Portion desktopSpan="whole">
20+
<Tabs
21+
tabs={[
22+
{
23+
key: "1",
24+
label: "200",
25+
content: (
26+
<>
27+
<p>
28+
<Badge type="success">SUCCESS</Badge> Bundled
29+
BAV request created successfully.
30+
</p>
31+
<hr className="tertiary" />
32+
<h5>Request</h5>
33+
<CodeBlockWithCopy language="json">
34+
{`POST /api/bundled-bav
35+
{
36+
"mobileNumber": "9876543210"
37+
}`}
38+
</CodeBlockWithCopy>
39+
<hr className="tertiary" />
40+
<h5>Response</h5>
41+
<CodeBlockWithCopy language="json">
42+
{`{
43+
"requestId": "f4ec6a99-a9a9-4f23-8dea-1da1b285a156",
44+
"url": "https://dg.setu.co/bundled-bav?payload=1234",
45+
"success": true,
46+
"message": "Bundled BAV request created",
47+
"traceId": "1-1234567890"
48+
}`}
49+
</CodeBlockWithCopy>
50+
<Callout type="tip">
51+
Note: Store the <code>requestId</code> from this
52+
response. You will receive the same{" "}
53+
<code>requestId</code> in the webhook
54+
notification when verification is complete,
55+
allowing you to match the webhook to the
56+
original request.
57+
</Callout>
58+
</>
59+
),
60+
},
61+
{
62+
key: "2",
63+
label: "400",
64+
content: (
65+
<>
66+
<p>
67+
<Badge type="failure">BAD REQUEST</Badge>{" "}
68+
Invalid product configuration or missing
69+
required parameters.
70+
</p>
71+
<hr className="tertiary" />
72+
<h5>Request</h5>
73+
<CodeBlockWithCopy language="json">
74+
{`POST /api/bundled-bav
75+
{
76+
"mobileNumber": "9876543210"
77+
}`}
78+
</CodeBlockWithCopy>
79+
<hr className="tertiary" />
80+
<h5>Response</h5>
81+
<CodeBlockWithCopy language="json">
82+
{`{
83+
"success": false,
84+
"message": "Bad request - invalid product configuration",
85+
"traceId": "1-1234567890"
86+
}`}
87+
</CodeBlockWithCopy>
88+
</>
89+
),
90+
},
91+
{
92+
key: "3",
93+
label: "500",
94+
content: (
95+
<>
96+
<p>
97+
<Badge type="failure">
98+
INTERNAL SERVER ERROR
99+
</Badge>{" "}
100+
Failed to create request due to internal error.
101+
</p>
102+
<hr className="tertiary" />
103+
<h5>Request</h5>
104+
<CodeBlockWithCopy language="json">
105+
{`POST /api/bundled-bav
106+
{
107+
"mobileNumber": "9876543210"
108+
}`}
109+
</CodeBlockWithCopy>
110+
<hr className="tertiary" />
111+
<h5>Response</h5>
112+
<CodeBlockWithCopy language="json">
113+
{`{
114+
"success": false,
115+
"message": "Failed to create request - internal error",
116+
"traceId": "1-1234567890"
117+
}`}
118+
</CodeBlockWithCopy>
119+
</>
120+
),
121+
},
122+
]}
123+
></Tabs>
124+
</Portion>
125+
</Row>
126+
127+
<hr class="tertiary" />
128+
129+
### Open URL in webview
130+
131+
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.
132+
133+
<Callout type="tip">
134+
Make sure to handle the webview lifecycle properly to provide a smooth user
135+
experience.
136+
</Callout>
137+
138+
<hr class="tertiary" />
139+
140+
### Handle redirect
141+
142+
Once the customer completes the verification process, they will be redirected to the `redirectUrl` configured in your product settings.
143+
144+
Set up an event listener in your app to detect this redirect and close the webview accordingly.
145+
146+
**Example event listener pattern**
147+
148+
<CodeBlockWithCopy language="javascript">
149+
{`// Detect when the webview navigates to your redirect URL
150+
webview.onNavigationStateChange = (navState) => {
151+
if (navState.url.startsWith(YOUR_REDIRECT_URL)) {
152+
// Close the webview
153+
closeWebview();
154+
// Continue with your app flow
155+
navigateToNextScreen();
156+
}
157+
};`}
158+
</CodeBlockWithCopy>
159+
160+
<hr class="tertiary" />
161+
162+
### Webhook notification
163+
164+
Once the verification is complete, Setu will send the bank account details to your configured webhook endpoint.
165+
166+
<Callout type="tip">
167+
The webhook payload will contain the same <code>requestId</code> that you
168+
received in the create request response. Use this to match the webhook
169+
notification with the original verification request.
170+
</Callout>
171+
172+
<br />
173+
174+
**Webhook payload**
175+
176+
<CodeBlockWithCopy language="json">
177+
{`{
178+
"requestId": "f4ec6a99-a9a9-4f23-8dea-1da1b285a156",
179+
"data": {
180+
"accountHolderName": "JOHN DOE",
181+
"bankAccountNumber": "1234567890",
182+
"bankAccountIfsc": "ICIC0005573",
183+
"bankName": "ICICI BANK"
184+
},
185+
"bavMethod": "PENNY_DROP",
186+
"success": true,
187+
"message": "Bank account verification successful",
188+
"timestamp": "2026-01-08T12:27:50.697274+00:00"
189+
}`}
190+
</CodeBlockWithCopy>
191+
192+
<Callout type="warning">
193+
Ensure your webhook endpoint is configured to accept POST requests and can
194+
handle the payload structure above.
195+
</Callout>
196+
197+
<hr class="tertiary" />
198+
199+
### Best practices
200+
201+
1. **Handle webhook retries** — Make your webhook endpoint idempotent as Setu may retry failed webhook deliveries
202+
2. **Store traceId** — Always store the `traceId` for debugging and support purposes
203+
3. **Handle timeouts** — Implement appropriate timeout handling for the webview
204+
205+
<WasPageHelpful />

0 commit comments

Comments
 (0)