From 00e7a8c5e71439e45ca0d0cbe62dfbeef1aad3ea Mon Sep 17 00:00:00 2001 From: Phaneendra Date: Thu, 9 Oct 2025 17:29:36 +0530 Subject: [PATCH 1/4] adding zto docs. also corrected authn page of additional apis --- docs/additional-apis/additional-apis.md | 2 +- docs/additional-apis/authn.md | 6 +- docs/additional-apis/zero-touch-onboarding.md | 216 ++++++++++++++++++ 3 files changed, 220 insertions(+), 4 deletions(-) create mode 100644 docs/additional-apis/zero-touch-onboarding.md diff --git a/docs/additional-apis/additional-apis.md b/docs/additional-apis/additional-apis.md index 3215aef..8ba3752 100644 --- a/docs/additional-apis/additional-apis.md +++ b/docs/additional-apis/additional-apis.md @@ -8,7 +8,7 @@ title: Additional APIs In addition to Orders APIs that conform to ONDC protocols, Cybrilla POA also offers additional APIs for AMC partners(i.e. distributors and advisors) to deliver certain value added services. These APIs have to be authenticated separately and a separate credentials are issued for the same. -|API|Environment|Base Url| +|API|Environment|Base URL| |---|---|---| |Authentication APIs*|Sandbox|https://s.finprim.com| |All other APIs|Sandbox|https://api.sandbox.cybrilla.com| diff --git a/docs/additional-apis/authn.md b/docs/additional-apis/authn.md index ac30132..c7193e5 100644 --- a/docs/additional-apis/authn.md +++ b/docs/additional-apis/authn.md @@ -9,14 +9,14 @@ title: Authentication ## Getting Started 1. Write an email to poa.support@cybrilla.com and register yourself as OAuth 2.0 client for partner authentication purposes. At present, access to POA additional APIs is provided only to AMC partners i.e. distributors and advisors. 2. We will share the `client_id` and `client_secret` -3. Use `POST /v2/auth/cybrillarta/token` endpoint and provide `client_id` and `client_secret` to generate token object. +3. Use partner token endpoint and provide `client_id` and `client_secret` to generate token object. 4. Use the generated token object's `access_token` to access additional POA APIs. 5. Every token object will have an expiry time. Ensure that you are creating a new token object if the existing token object is expired. ## Getting partner token For partner tokens, we are using Client Credentials flow. This flow is recommended for server-side (aka confidential) client applications with no end-user, which normally describes server-to-server communication. The application needs to securely store its client ID and secret and pass them in exchange for an access token. -`POST /v2/auth/cybrillarta/token` +**Sandbox partner token endpoint**: `POST /v2/auth/cybrillarta/token` ### Headers @@ -35,7 +35,7 @@ For partner tokens, we are using Client Credentials flow. This flow is recommend ### Sample Request ``` -curl --location '{{base_url}}/poa/auth/token' \ +curl --location '{{base_url}}/{{sandbox_partner_token_endpoint}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ diff --git a/docs/additional-apis/zero-touch-onboarding.md b/docs/additional-apis/zero-touch-onboarding.md new file mode 100644 index 0000000..86c66d5 --- /dev/null +++ b/docs/additional-apis/zero-touch-onboarding.md @@ -0,0 +1,216 @@ +--- +sidebar_position: 2 +sidebar_label: Zero Touch Onboarding APIs +title: Zero Touch Onboarding APIs +--- + +The Zero Touch Onboarding APIs lets a partner to attempt fetching certain details of the investor from a couple of third party sources. At present, bank account details and demographic information of the investor can be attempted to fetch using the below 2 APIs - +1. Bank Account Lookup API +2. Customer Data Lookup API + +## Bank account lookup + +The Bank account lookup API lets a partner fetch the bank account details of the investor that is registered against the primary VPA / UPI ID. + + +### Bank account lookup object + +```json +{ + "object": "bank_account_lookup", + "id": "bal_32PUeQZKweX8ZBSXY22Iqq9u3yg", + + "status": "success", + + "source_ref_id": "1a478f56-54df-41aa-951a-b2c7edbada2", + "mobile_number": "9012390123", + + "data": { + "account_holder_name": "Rakshith Agarwal", + "account_number": "98123108291821", + "ifsc_code": "utib0003076" + } +} +``` + +|Attribute|Type|Comments| +|-|-|-| +|object|string|Value is `bank_account_lookup`. String representing the object type. Objects of the same type share the same value| +|id|string|Unique identifier of the `bank_account_lookup` object +|status|enum|The status of the `bank_account_lookup` object. Possible values are - `pending`, `successful`, `failed`| +|source_ref_id|string|A unique identifier that could be used as a an internal reference ID at the API request source| +|mobile_number|string|Mobile number of the customer against which the bank account lookup was attempted| + +### Create Bank Account Lookup + +`POST /v2/bank_account_lookups` + +This API lets you create a bank account lookup object. +```json +curl --location '{{base_url}}/v2/bank_account_lookups' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data '{ +"mobile_number": "9012390123" +} +' +``` + +#### Request parameters + +|Name|Mandatory|Type|Comments| +|-|-|-|-| +|mobile_number|yes|string|Customer's mobile number| +|source_ref_id|no|string|A unique identifier that could be used as a an internal reference ID at the API request source. If something is passed here, the same value would be used in the object. If nothing is passed here, Cybrilla will assign a random generated identifier as the value| + +> **NOTE:** The `bank_account_lookup` object will be returned as the response. + + +### Fetch Bank Account Lookup + +`GET /v2/bank_account_lookups/:id` + +This API lets you fetch a bank account lookup object. +```json +curl --location '{{base_url}}/v2/bank_account_lookups/:id' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' +``` + +#### Query parameters +|Name|Mandatory|Type|Comments| +|-|-|-|-| +|id|yes|string|ID of the `bank_account_lookup` object| + +> **NOTE:** The `bank_account_lookup` object will be returned as the response. + + +
+--- + + + +## Customer Data Lookup API + +The Customer data lookup API lets a partner fetch certain demographic information of the investor from certain third party sources. + +### Customer data lookup object + +```json +{ + "object": "customer_data_lookup", + "id": "cdl_32PUk5aUMxb7pLGdEGsyk9cRF9t", + + "status": "success", + + "source_ref_id": "910563db-deb1-44b3-9e34-5819c396de54", + "mobile_number": "9012390123", + "name": "Rakshith", + + "data": { + "name": "Rakshith Agarwal", + "date_of_birth": "1992-03-15", + "gender": "male", + "pan": "jsdpr9021f", + "aadhaar_number": null, + "income_slab": "upto_1lakh", + "occupation": null, + "addresses": [ + { + "line": "123 36th cross 24th main jayanagar 4th t block bangalore south", + "state": "karnataka", + "pincode": "560041", + "reported_date": "2025-08-31" + } + ], + "email_addresses": [ + { + "email": "iamagarwalrakshith@gmail.com", + "reported_date": "2025-06-30" + } + ] + } +} +``` + +|Attribute|Type|Comments| +|-|-|-| +|object|string|Value is `customer_data_lookup`. String representing the object type. Objects of the same type share the same value| +|id|string|Unique identifier of the `customer_data_lookup` object +|status|enum|The status of the `customer_data_lookup` object. Possible values are - `pending`, `successful`, `failed`| +|source_ref_id|string|A unique identifier that could be used as a an internal reference ID at the API request source| +|mobile_number|string|Mobile number of the customer against which the data lookup was attempted| +|name|string|Name of the customer| +|data|hash|Hash containing all the data of the customer. The `data` would be available only for 30 minutes since `customer_data_lookup.status` was marked `successful`| + +#### `data` hash +|Attribute|Type|Comments| +|-|-|-| +|name|string|Customer's name| +|date_of_birth|string|Customer's date of birth| +|gender|enum|Customer's gender. Possible values are - `male`, `female`, `transgender`| +|pan|string|Customer's PAN number| +|aadhaar_number|string|Last 4 digits of customer's Aadhaar number| +|income_slab|enum|Customer's income slab. Possible values are - `upto_1lakh`, `above_1lakh_upto_5lakh`, `above_5lakh_upto_10lakh`, `above_10lakh_upto_25lakh`, `above_25lakh_upto_1cr`, `above_1cr`| +|occupation|enum|Customer's occupation. Possible values are - `business`, `professional`, `retired`, `house_wife`, `student`, `public_sector_service`, `private_sector_service`, `government_service`, `others`, `agriculture`, `doctor`, `forex_dealer`, `service`| +|addresses|array of `address` hashes|List of customer's addresses| +|email_addresses|array of `email_address` hashes|List of customer's email addresses| + +#### `address` hash +|Attribute|Type|Comments| +|-|-|-| +|line|string|Address line| +|state|string|State| +|pincode|string|Pincode| +|reported_date|string|Date as on which this address was reported by the customer| + +#### `email_address` hash +|Attribute|Type|Comments| +|-|-|-| +|email|string|Email address of the customer| +|reported_date|string|Date as on which this email address was reported by the customer| + +### Create Customer Data Lookup + +`POST /v2/customer_data_lookups` + +This API lets you create a customer data lookup object. +```json +curl --location '{{base_url}}/v2/customer_data_lookups' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data '{ +"name": "Rakshith", +"mobile_number": "9012390123" +} +' +``` + +#### Request parameters + +|Name|Mandatory|Type|Comments| +|-|-|-|-| +|name|yes|string|Customer's name| +|mobile_number|yes|string|Customer's mobile number| +|source_ref_id|no|string|A unique identifier that could be used as a an internal reference ID at the API request source. If something is passed here, the same value would be used in the object. If nothing is passed here, Cybrilla will assign a random generated identifier as the value| + +> **NOTE:** The `customer_data_lookup` object will be returned as the response. + + +### Fetch Customer Data Lookup + +`GET /v2/customer_data_lookups/:id` + +This API lets you fetch a customer data lookup object. +```json +curl --location '{{base_url}}/v2/customer_data_lookups/:id' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' +``` + +#### Query parameters +|Name|Mandatory|Type|Comments| +|-|-|-|-| +|id|yes|string|ID of the `customer_data_lookup` object| + +> **NOTE:** The `customer_data_lookup` object will be returned as the response. \ No newline at end of file From 4f42f5cb6c2b3b7a75ee430b4c4a5ba269d1a61f Mon Sep 17 00:00:00 2001 From: Phaneendra Date: Thu, 9 Oct 2025 17:46:56 +0530 Subject: [PATCH 2/4] added note --- docs/additional-apis/zero-touch-onboarding.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/additional-apis/zero-touch-onboarding.md b/docs/additional-apis/zero-touch-onboarding.md index 86c66d5..262a12f 100644 --- a/docs/additional-apis/zero-touch-onboarding.md +++ b/docs/additional-apis/zero-touch-onboarding.md @@ -213,4 +213,9 @@ curl --location '{{base_url}}/v2/customer_data_lookups/:id' \ |-|-|-|-| |id|yes|string|ID of the `customer_data_lookup` object| -> **NOTE:** The `customer_data_lookup` object will be returned as the response. \ No newline at end of file +> **NOTE:** The `customer_data_lookup` object will be returned as the response. + +
+--- + +> **NOTE:** Both these APIs **attempt** to fetch data from third-party sources provided they are available. Once data is fetched, accuracy isn’t validated. We strongly advise you to share the information with the investor and proceed only after their approval. \ No newline at end of file From 67eb80b29bd8731b3a803bc99118eeeeb8cb39c6 Mon Sep 17 00:00:00 2001 From: Phaneendra Date: Thu, 9 Oct 2025 17:49:28 +0530 Subject: [PATCH 3/4] API name format correction --- docs/additional-apis/zero-touch-onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/additional-apis/zero-touch-onboarding.md b/docs/additional-apis/zero-touch-onboarding.md index 262a12f..80c884d 100644 --- a/docs/additional-apis/zero-touch-onboarding.md +++ b/docs/additional-apis/zero-touch-onboarding.md @@ -8,7 +8,7 @@ The Zero Touch Onboarding APIs lets a partner to attempt fetching certain detail 1. Bank Account Lookup API 2. Customer Data Lookup API -## Bank account lookup +## Bank Account Lookup API The Bank account lookup API lets a partner fetch the bank account details of the investor that is registered against the primary VPA / UPI ID. From 3421cc95518b7ec51a22e026979fb7d9b7907340 Mon Sep 17 00:00:00 2001 From: Phaneendra Date: Thu, 9 Oct 2025 18:07:53 +0530 Subject: [PATCH 4/4] Added PV error codes --- docs/additional-apis/pre-verification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/additional-apis/pre-verification.md b/docs/additional-apis/pre-verification.md index d675665..da46b9f 100644 --- a/docs/additional-apis/pre-verification.md +++ b/docs/additional-apis/pre-verification.md @@ -99,14 +99,14 @@ The Pre Verification API lets a partner verify certain demographic information o |Attribute|Type|Remarks| |---|---|---| |status|string|1. `verified`: Investor can proceed to invest
2.`failed`:Investor cannot invest. Please check code for more details on failure| -|code|string|1. `kyc_unavailable`: Investor cannot invest because KYC is unavailable
2.`upstream_error`: There was an error contacting upstream to check readiness
3.`unknown`: Investor is KYC Non compliant but the reason for non-compliance is not known| +|code|string|1. `kyc_unavailable`: Investor cannot invest because KYC is unavailable
2.`kyc_incomplete`: Investor's KYC is verified/registered and Aadhaar is not linked to this record. Investor has to raise a modification request to set this right
3.`upstream_error`: There was an error contacting upstream to check readiness
4.`unknown`: Investor is KYC Non compliant but the reason for non-compliance is not known| |reason|string|Descriptive reason for the failure. Should be only relied for understanding the failure and not for programmatically interpreting the failure. For programmatic failure interpretation always use `code`| ### Bank Accounts hash |Attribute|Type|Remarks| |---|---|---| |status|string|1. `verified`: Investor can proceed to invest
2.`failed`:Investor cannot invest. Please check code for more details on failure| -|code|string|1.`awaiting_approval_for_manual_verification_with_proof` - This bank account needs a manual verification along with an associated bank account proof along with the approval for manual verification
2. `bank_account_proof_required` This bank account needs a manual verification and in order to initiate it, the bank account proof should be provided| +|code|string|1.`awaiting_approval_for_manual_verification_with_proof`: This bank account needs a manual verification along with an associated bank account proof along with the approval for manual verification
2. `bank_account_proof_required`: This bank account needs a manual verification and in order to initiate it, the bank account proof should be provided
3.`digital_verification_failure`: The workflow to verify this bank account failed. You need to retry| |value.account_number|string|Bank account number| |value.ifsc_code|string|IFSC code associated with the bank account| |value.account_type|string|Bank account type|