Core Specification - Loan domain

[karntrehan]

Context

We are building a portal for farmers to apply for crop loans. Democratising the loan search & selection process is a very valid usecase for using Beckn.

Attaching below a broad flow of the application currently:

We believe there is a valid usecase to add mortgage to the core spec domain itself. The core support for applicant, application, guarantee, eligibility, financer, e-signing would make the API much cleaner.

Problem

Currently we are extensively using Tags to communicate between the portal and financers / banks as there is lack of support of common mortgage elements like: eligibility, guarantee, sanctioning, etc..

Proposed Solution

Create a new core spec for mortgage. We are taking the first crack at this & proposing it look something like this:

{
  "context": {
    "action": "init",
    "domain": "mortgage"
  },
  "message": {
    "order": {
      "items": {
        "mortgage_terms": {
          "interest": {
            "rate": 0,
            "type": "simple_interest"
          },
          "tenure": {
            "unit": "months",
            "quantity": 18
          }
        }
      },
      "eligibility": {
        "max": 1000,
        "min": 100,
        "source": {
          "id": "",
          "name": "",
          "url": ""
        }
      },
      "guarantee": {
        "type": "immovable",
        "value": {
          "currency": "",
          "min_value": 0,
          "max_value": 100
        },
        "proof_url": "http://xyz.com"
      }
    }
  }
}

Please bear in mind this is a WIP and we are open to any and all feedback for this.

Examples

Shared above. Once feedback is received would add more.

References

• Whimsical flow

[ravi-prakash-v]

Hi @karntrehan. Glad to hear that you are implementing beckn protocol for agri use cases. However, I would like to correct the mental model we are having here before we proceed.

Firstly, saying "Create a new core spec for mortgage" is an oxymoron. The core specs do not change. You should say "Create an adaptation of core spec for mortgage use cases".

The above example that you shared does not comply with the beckn protocol standard. For example, the core spec does not have any field called mortgage terms, tenure, eligibility or guarantee. And it will probably never have one unless it can be used across multiple sectors. These are merely finance sector-specific objects that must have a generic equivalent in the core schema. If it doesn't, then the core spec must be upgraded to include a generic equivalent of the sector-specific schema.

Having said that, the method to implement a new use case in beckn consist of the following broad steps:-

1. Map the actors in agro sector to actors in beckn. Like Who is the consumer? who is the provider? who is the agent? who is the consumer platform? who is the provider platform?
2. Map the core interactions between consumer and provider to the standard API endpoints of beckn. For example, "Search for loan products" maps to search endpoint. "Return Loan products" maps to on_search. "Final application form submitted" maps to confirm, and so on...
3. Map the agri sector-specific objects and attributes to the core schema of beckn. Like Loan Product maps to Item schema. Financer maps to Provider, Loan Sanction and Disbursement maps to Fulfillment. A Relationship Manager could map to Agent. Get it?
4. Bear in mind: EXTENSIONS ARE NOT ALLOWED IN BECKN PROTOCOL. Any extended fields that must be captured by a provider to process a loan can be done through the XInput Schema. Any sector-specific fields that are merely for display, filtering, sorting etc must be transmitted via the Tags schema. To know more about this, please read the RFC on Xinput schema here; and the Tags schema here
5. Lastly, if there are still interactions and objects that you are unable to map to the core schema, then you can start a discussion thread in the lines of "How do I implement this interaction using beckn?"; or "How do I represent this object in beckn?". If it is truly un-mappable to beckn API or schema, then we will update the core spec and release a new version that supports the new use case and publish a recommendation.

Design your mapping assuming an application that has implemented beckn protocol for say, Retail should have almost zero engineering overhead to discover and avail loan products. Adding new fields and schema will require re-engineering and re-arch. As a consumer, I should be able to discover a loan product, add it to my cart, checkout and confirm my loan application just like I would do in an e-commerce flow. That's the test you must perform when designing an adaptation to a new use case.

Hope this helps...

[charanpreet-s]

Hi @ravi-prakash-v, Thank you for your valuable insights. Your message has provided us with a clearer understanding of how to implement the Beckn Protocol for the loans domain. We appreciate the correction in terminology, and we will now proceed to discuss an adaptation of the core spec specifically tailored for loan use cases.

Based on your feedback, we have re-evaluated our approach and designed a mapping that aligns with the standard API endpoints of Beckn. We have also made sure to map the loan-specific objects and attributes to the core schema of Beckn. To ensure compliance, we tried to avoid extensions as far as possible and used the XInput Schema and Tags Schema appropriately for any additional fields and sector-specific data.

Purpose
The Loan Domain Adaptation of the Beckn Specification is being created to adapt the core Beckn specification to the specific attributes and requirements of the loans domain. The purpose of this adaptation is to provide a standardized framework and protocols that cater specifically to loan-related transactions and interactions.

By adapting the core Beckn specification to the loan domain, our goal is to seamlessly incorporate loan-specific attributes such as interest rates, repayment terms, eligibility criteria, and other relevant parameters into the existing Beckn framework. This adaptation aims to enhance interoperability and streamline communication among loan service providers, borrowers, and other stakeholders.

The Loan Domain Adaptation will facilitate efficient and standardized loan interactions, improving transparency and enabling informed decision-making for borrowers. It will enable loan service providers to integrate their offerings into the broader Beckn ecosystem, ensuring seamless discovery, selection, and fulfilment of loan products.

Approach
We examined 6 forms used by different banks, went through 280 fields, and identified generic parameters for the loans domain. Using Beckn's core spec as a reference, we've incorporated these parameters into existing keys and objects. For any additional parameters, we've introduced new keys/fields and objects to ensure seamless integration.

The domain is loans and not mortgages or finance. Mortgages are a subset of loans. Finance is too broad a domain for us to work on. Loans can be expanded at a later stage to cover a broader finance sector but we currently do not have the aim to do so.

For Search and other product listing APIs, the Beckn schema doesn’t have loan-specific terms. Following is the proposed change for the base object for searching the Item which will then populate in all the listings.

Json

Description

{ "context" : { "domain" : "loans" }, "message" : { "order" : { "xinput" : { "form" : { "data" : { // Additional data specific // to lender use case to be submitted here "social_category" : "general", "minority" : "String" } } }, "fulfillments" : [{ "customer" : { "constitution" : "XYZ LLC", // new field "activity" : "marketing" // new field "person" : { // person object "creds" : [{ // creds object // all the lists of proofs related to person // or business will be uploaded in this array }], "education": { // new component object "level": "bachelor", "degree": "Bachelor of Science", "field": "Computer Science", "completionYear": 2023 }, "father_name" : "String", // new field "mother_name" : "String", // new field "care_of" : "String", // new field "disabled" : "boolean", // new field "nationality" : "String", // new field "marital_status" : "String", // new field "occupation" : "String", // new field "residential_status" : "String" // new field }, "locations" : [ // new object array // Location component ], } }], "application" : { // new loan object "purpose" : "String", "collateral" : { // handles collateral // for different loan types "location": { // location object }, "type": "String", "descriptor" : { // descriptor object }, "price" : { // price object }, "owners" : { // Person object }, "creds" : [ // Creds object array ], "tags": [], "xinput" : {} }, "finance" : { // new object // for listing all finances of the applicant "earnings" : [{ // new income Object "id":"String". "amount" : "343423", "descriptor" : {}, "creds" : [], "type" : "direct/indirect", "taxable" : "boolean" }], "assets" : [{ // new financial object "id" : "String", "descriptor" : {}, "price" : {}, "creds" : [] }], "liabilities" : [{ // financial object }], "guarantor" : { "person" : { // person object }, "liabilities" : [] // income object } }, "nominees" : [] // array of person object }, "quote" : { "price" : { // price object "value" : 800000 // loan amount } }, "items" : [{ "time" : { "duration" : "P20Y" // tenure } }] } } }

context: domain: "loans" - Specifies new domain for loans message: order: Represents an order-related message. data: Contains additional data specific to the lender use case, such as: social_category: Specifies the social category (e.g., "general"). minority: Indicates whether the applicant belongs to a minority group (e.g., "yes"). fulfillments: Represents an array of fulfillments for the order. customer: Contains customer-related details. constitution: Specifies the constitution of the customer (e.g., "XYZ LLC"). activity: Specifies the activity of the customer (e.g., "marketing"). person: Represents a person object associated with the customer. creds: Represents an array of credentials or proofs related to the person or business. education: Represents the education details of the person. level: Specifies the education level (e.g., "bachelor"). degree: Specifies the degree obtained (e.g., "Bachelor of Science"). field: Specifies the field of study (e.g., "Computer Science"). completionYear: Indicates the completion year of education (e.g., 2023). father_name: Specifies the name of the person's father. mother_name: Specifies the name of the person's mother. care_of: Specifies the care-of information for the person. disabled: Indicates whether the person has a disability (boolean value). nationality: Specifies the nationality of the person. marital_status: Specifies the marital status of the person. occupation: Specifies the occupation of the person. residential_status: Specifies the residential status of the person (e.g., "Resident Individual/NRI/Other"). locations: Represents an array of location objects associated with the customer. application: Represents the loan application details. purpose: Specifies the purpose of the loan. collateral: Handles collateral details for different loan types. location: Represents the location object associated with the collateral. type: Specifies the type of collateral. descriptor: Represents the descriptor object associated with the collateral. price: Represents the price object associated with the collateral. owners: Represents the owner details (person object) associated with the collateral. creds: Represents an array of credentials or proofs associated with the collateral. tags: Contains additional tags related to the collateral. xinput: Contains additional input data specific to the collateral. finance: Represents the financial details of the loan applicant. earnings: Represents an array of income objects for the applicant. id: Specifies the ID of the earnings. amount: Specifies the amount of earnings. descriptor: Represents the descriptor object associated with earnings. creds: Represents an array of credentials or proofs associated with earnings. type: Indicates whether earnings are direct or indirect. taxable: Indicates whether earnings are taxable (boolean value). assets: Represents an array of financial item objects (assets) for the applicant. id: Specifies the ID of the asset. descriptor: Represents the descriptor object associated with the asset. price: Represents the price object associated with the asset. creds: Represents an array of credentials or proofs associated with the asset. liabilities: Represents an array of financial item objects (liabilities) for the applicant. guarantor: Contains information about the guarantor. person: Represents the person object associated with the guarantor. liabilities: Represents an array of income objects (liabilities) associated with the guarantor. nominees: Represents an array of person objects (nominees). quote: Represents a quote for the loan. price: Represents the price object associated with the quote. value: Specifies the loan amount for the quote. items: Represents an array of items. time: Represents the time object associated with the item. duration: Specifies the tenure or duration of the item (e.g., "P20Y").

Adaptations in Submission/Init/Confirm

Json

Description

{ "compensation" : { // New Field "interest" : { "type" : "fixed", "min_value" : Float, "max_value" : Float, "offered_value" : Float, "estimated_value" : Float, "calculation_method" : "amortized" }, "fee" : [{ "id":"22", "type":"FileCharge", "price" : { // Price Object }, { "id":"23", "type":"Processing Fee", "price" : { // Price Object } // ..... }] }, "time" : { // tenure "duration" : "P15Y/P30Y" }, // "quantity" renamed to "amount" for loan amount "amount" : { // allocated // minimum // maximum // available // selected }, "eligibility" : { // New Field "age": { "minimum": 18, "maximum": 65 }, "income": { "amount": { "value": 3000, "currency": "USD" }, "sourceTypes": ["self-employment"] }, "creditScore": [ { "minimum": 650 "type" : "Equifax" }, { "minimum": 750 "type" : "CIBIL" } ], "employment": { "status": ["employed"], "time" : { // time object } }, "residence": { "Location" : { // location object } "time" : { // time object } }, "debtToIncomeRatio": { "maximum": 0.4 }, "collateral": [{ "required": true, "description": "Real estate property", "value": { // Price Object } }], "guarantor": { "required": false, "description": "No guarantor required", "eligibilityCriteria": "Good credit score" }, "tags" : {} }, "descriptor" : { "short_desc" : "" "long_desc" : "For additional read only information" } }

compensation: interest: Represents the interest details for the loan. type: Specifies the type of interest (e.g., fixed). min_value: Indicates the minimum value of the interest rate. max_value: Indicates the maximum value of the interest rate. offered_value: Specifies the offered value of the interest rate. estimated_value: Indicates the estimated value of the interest rate. calculation_method: Specifies the calculation method for the interest (e.g., amortized or simple interest). fee: Represents an array of fees associated with the loan. id: Specifies the ID of the fee. type: Indicates the type of fee. price: Represents the price object associated with the fee. time: duration: Specifies the duration or tenure of the loan (e.g., "P15Y" or "P30Y"). amount: Contains various attributes related to the loan amount, such as: allocated: Represents the allocated amount for the loan. minimum: Specifies the minimum loan amount. maximum: Specifies the maximum loan amount. available: Indicates the available loan amount. selected: Represents the selected loan amount. eligibility: Contains eligibility criteria for the loan application. age: Specifies the age criteria for the applicant. minimum: Indicates the minimum age requirement. maximum: Specifies the maximum age limit. income: Represents the income details for the applicant. amount: Contains the income amount and currency information. sourceTypes: Specifies the types of income sources (e.g., employment, self-employment, investment). creditScore: Represents the credit score requirements for the loan application. Contains an array of objects with: minimum: Specifies the minimum credit score requirement. type: Indicates the type of credit score provider (e.g., Equifax, CIBIL). employment: Specifies the employment details of the applicant. status: Represents the employment status options (e.g., employed, self-employed, unemployed). time: Contains time-related information for employment. residence: Represents the residence details of the applicant. Location: Contains the location object associated with the residence. time: Contains time-related information for the residence. debtToIncomeRatio: Specifies the maximum debt-to-income ratio allowed. collateral: Represents an array of collateral details associated with the loan. required: Indicates whether collateral is required. description: Provides a description of the collateral (e.g., real estate property). value: Represents the price object associated with the collateral. guarantor: Contains information about the guarantor requirements for the loan. required: Indicates whether a guarantor is required. description: Provides a description of the guarantor requirements. eligibilityCriteria: Specifies the eligibility criteria for the guarantor. tags: Contains any additional tags or metadata associated with the loan. descriptor: short_desc: Represents a short description of the loan. long_desc: Provides additional read-only information about the loan.

Do let us know the next steps.

[kshitijahuja]

@karntrehan, @charanpreet-s:

Just a suggestion:

I noticed that your schema has fulfillments array with customers.disabled property as boolean. You might want to consider expanding this to include the type and extent of disability given different govt rules/regulations are mandated based on the extend of disability.

Or it is for @ravi-prakash-v to advise if this spec has already been included anywhere in the core schema?

[karntrehan]

Hie @ravi-prakash-v and team hopefully you have gone through the above message. Do let us know the next steps.

[emmayank]

Hi @karntrehan ,

Beckn has already published API Specs for financial services, which has an example of personal loans. Please have a look here - https://github.com/beckn/financial-services/tree/main/examples/personal-loans.

Additionally, you can also create an issue in the Financial-services repository, if any flow explained in personal-loans example is unmapped with your usecase ( mortgage-loan),