From b7b7d20d25f0c0723d4b4f1a94aba4adc22b9fcd Mon Sep 17 00:00:00 2001 From: Abhishek Jha Date: Thu, 8 Jan 2026 16:53:02 +0530 Subject: [PATCH] Added bundled bav doc files --- content/data/bav/bundled-bav.mdx | 6 + .../data/bav/bundled-bav/api-integration.mdx | 205 ++++++++++++ .../data/bav/bundled-bav/api-reference.mdx | 294 ++++++++++++++++++ content/data/bav/bundled-bav/quickstart.mdx | 104 +++++++ content/redirects.json | 1 + 5 files changed, 610 insertions(+) create mode 100644 content/data/bav/bundled-bav.mdx create mode 100644 content/data/bav/bundled-bav/api-integration.mdx create mode 100644 content/data/bav/bundled-bav/api-reference.mdx create mode 100644 content/data/bav/bundled-bav/quickstart.mdx diff --git a/content/data/bav/bundled-bav.mdx b/content/data/bav/bundled-bav.mdx new file mode 100644 index 00000000..d1fa4870 --- /dev/null +++ b/content/data/bav/bundled-bav.mdx @@ -0,0 +1,6 @@ +--- +sidebar_title: Bundled BAV +page_title: Bundled Bank Account Verification +order: 2 +visible_in_sidebar: true +--- diff --git a/content/data/bav/bundled-bav/api-integration.mdx b/content/data/bav/bundled-bav/api-integration.mdx new file mode 100644 index 00000000..d0934f57 --- /dev/null +++ b/content/data/bav/bundled-bav/api-integration.mdx @@ -0,0 +1,205 @@ +--- +sidebar_title: API integration +page_title: Bundled BAV API integration +order: 2 +visible_in_sidebar: true +--- + +## 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. + + + + +

+ SUCCESS 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. + + + ), + }, + { + key: "2", + label: "400", + content: ( + <> +

+ BAD REQUEST{" "} + Invalid product configuration or missing + required parameters. +

+
+
Request
+ + {`POST /api/bundled-bav +{ + "mobileNumber": "9876543210" +}`} + +
+
Response
+ + {`{ + "success": false, + "message": "Bad request - invalid product configuration", + "traceId": "1-1234567890" +}`} + + + ), + }, + { + key: "3", + label: "500", + content: ( + <> +

+ + INTERNAL SERVER ERROR + {" "} + Failed to create request due to internal error. +

+
+
Request
+ + {`POST /api/bundled-bav +{ + "mobileNumber": "9876543210" +}`} + +
+
Response
+ + {`{ + "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. + + + 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 + + diff --git a/content/data/bav/bundled-bav/api-reference.mdx b/content/data/bav/bundled-bav/api-reference.mdx new file mode 100644 index 00000000..19d7cf20 --- /dev/null +++ b/content/data/bav/bundled-bav/api-reference.mdx @@ -0,0 +1,294 @@ +--- +sidebar_title: API reference +page_title: Bundled BAV API reference +order: 3 +visible_in_sidebar: true +--- + +## API reference + +This document provides detailed API specifications for Bundled Bank Account Verification. + +
+ +### Create Bundled BAV request + +Create a verification request to generate a URL for the bundled BAV flow. + + + + + + + + + + + + + + + + + + + + +
Method + POST +
Path + /api/bundled-bav +
Sandbox base URL + https://dg-sandbox.setu.co +
Production base URL + https://dg.setu.co +
+ +
+ +#### Headers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
HeaderTypeDescriptionRequired
+ x-client-id + StringYour client ID provided by SetuYes
+ x-client-secret + StringYour client secret provided by SetuYes
+ x-product-instance-id + StringYour product instance ID for Bundled BAVYes
+ +
+ +#### Request body + + + + + + + + + + + + + + + + + + +
ParameterTypeDescriptionRequired
+ mobileNumber + StringCustomer's 10-digit mobile numberYes
+ +
+ +#### Response parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
+ requestId + String (UUID) + Unique identifier for this verification request. Store this + value to match with the webhook notification. +
+ url + StringVerification URL to be opened in webview
+ success + BooleanIndicates if request was successful
+ message + StringDescriptive message about the response
+ traceId + StringUnique identifier for tracking the request
+ +
+ +### Webhook notification + +After the customer completes the verification, Setu sends a webhook notification to your configured endpoint. + + + + + + + + + + + + +
Method + POST +
EndpointYour configured webhook URL
+ +
+ +#### Webhook payload + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
+ requestId + String (UUID)Unique identifier for this verification request
+ data + ObjectBank account details (see below)
+ bavMethod + String (Enum) + BAV method used for verification. Values:{" "} + PENNY_DROP, REVERSE_PENNY_DROP,{" "} + MOBILE_TO_BANK or VPA_TO_BANK +
+ success + BooleanIndicates if verification was successful
+ message + StringDescriptive message about the verification result
+ timestamp + StringUTC timestamp of verification
+ +
+ +#### Data object + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
+ accountHolderName + StringName of the account holder
+ bankAccountNumber + StringBank account number
+ bankAccountIfsc + StringIFSC code of the bank branch
+ bankName + StringName of the bank
+ + diff --git a/content/data/bav/bundled-bav/quickstart.mdx b/content/data/bav/bundled-bav/quickstart.mdx new file mode 100644 index 00000000..3483c5c6 --- /dev/null +++ b/content/data/bav/bundled-bav/quickstart.mdx @@ -0,0 +1,104 @@ +--- +sidebar_title: Quickstart +page_title: Quickstart for Bundled BAV +order: 1 +visible_in_sidebar: true +--- + +## Bundled Bank Account Verification + +### What is Bundled BAV? + +Setu's Bundled Bank Account Verification flow allows you to verify your customers' bank accounts with one orchestrated flow that supports multiple BAV methods and returns a unified response. + +You can simply create a request with the customer's phone number, which generates a verification URL to start the BAV journey. + +
+ +### Which BAV methods are supported? + +1. Penny Drop +2. Reverse Penny Drop +3. Mobile to Bank Account +4. UPI ID to Bank Account + +
+ +### How does it work? + +1. **Create a verification request** — Call the API with your customer's phone number to generate a verification URL +2. **Open URL in webview** — Display the URL in a webview within your app +3. **Customer completes verification** — The customer verifies their bank account using any of your enabled methods +4. **Receive webhook notification** — Once verification is complete, bank account details are sent to your configured webhook endpoint +5. **Close webview** — Set up an event listener to detect the redirect and close the webview + +
+ +### Step 1 — Get API credentials + +Contact Setu at onboarding@setu.co to get your API credentials and configure your product instance. + +
+ +### Step 2 — Configure product settings + +Work with Setu to configure the following for your product instance: + +- List of supported BAV methods +- Webhook notification URL for receiving verification results +- Redirect URL for post-verification navigation +- Primary theme color (e.g., primary button background color) +- Primary foreground color (e.g., primary button text color) +- Logo URL (optional) + +
+ +### Step 3 — Test on sandbox + +Use the sandbox environment to test the Bundled BAV flow: + +**Sandbox base URL** — `https://dg-sandbox.setu.co` + +##### API integration + +Refer to the API integration guide for detailed implementation steps. + +
+ +### Next steps + + + + + + API Integration + +

+ Learn how to integrate the Bundled BAV API into your + application. +

+ + + + + + API Reference + +

Complete API reference with request and response schemas.

+ + + + + diff --git a/content/redirects.json b/content/redirects.json index 1bbfe5a4..4ef6ae2c 100644 --- a/content/redirects.json +++ b/content/redirects.json @@ -74,6 +74,7 @@ "/data/bav/api-integration": "/data/bav/penny-drop/api-integration", "/data/bav/api-integration/sync": "/data/bav/penny-drop/api-integration/sync", "/data/bav/api-integration/async": "/data/bav/penny-drop/api-integration/async", + "/data/bav/bundled-bav": "/data/bav/bundled-bav/quickstart", "/data/pan": "/data/pan/quickstart", "/data/esign": "/data/esign/overview", "/data/digilocker": "/data/digilocker/overview",