Domain Object Specification

Metadata

KeyTypeValidationsMandatoryDescription
versionStringMin Length : 1
Max Length: 6
YesVersion of the API being used. NPCI may host multiple versions for supporting gradual migration. As of this specification, default production version is "1.0".
timestampISODateTime
YYYY-MM-DDThh:mm:ssZ+/-hh:mm (eg 1997-07-16T19:20:30+05:30) where; YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) Z +/- hh:mm = time zone designator (Z) followed by time zone difference from GMT in hours and minutes. THIS IS OPTIONAL. If not provided, it is assumed to be IST (+5.30)
Min Length : 1
Max Length : 255
YesTime of request from the creator of the message. API request time stamp. Since timestamp plays a critical role, it is highly recommended that devices are time synchronized with a time server.
traceIdAlphanumericLength : 35YesMessage identifier-used to correlate between the request and response. The unique identifier created by the originator of the message and will be used to correlate the response with the original request
orgIdAlphanumericMin Length : 1
Max Length : 35
YesUnique identifier for the organization in the ecosystem. In case of LSPs it will LSP id, for lenders it will be the FIUid and so on

Sample json

{
   "version": "1.0",
   "orgId": "LSP123",
   "timestamp": "2018-12-06T11:39:57.153Z",
   "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
}

Response

This object is used to capture errors.

KeyTypeValidationsMandatoryDescrioption
errorStringLength : 35YesErrors in the current request received.If no errors are found, error = 0. For example, if a mandatory attribute is missing, error code should capture that

LoanApplication

KeyTypeValidationsDescription
createdDateISODateTimeTime when the loan application was created
loanApplicationIdAlphanumericLength : 35UUID for the loan application. Generated by LSP
offersArray OfferOffers given by lender for a the loan application
typeCASHFLOW | PERSONAL | HOME | VEHICLE | BUSINESSENUMExpandable Enum. Captures the type of loan. Will be Cash Flow for invoice based loans.
borrowerBorrowerDetails of the Borrower
collateralsArray CollateralDetails of the instruments against which the user wishes to take loan. If no data is there to be sent, an empty array block can be passed.
guarantorsArray GuarantorsList of guarantors that the borrowers have for the loan. If no data is there to be sent, an empty array block can be passed.
applicantsArray ApplicantList of applicants for the loan. If no data is there to be sent, an empty array block can be passed
termsLoanTermsTerms of loan agreement
descriptionStringMax Length : 1000A short description of the loan application
urlStringMax Length: 1000For any new data that needs to be passed as a link
extensibleDataJSONFor any new data that needs to be added

Borrower

KeyTypeValidationsMandatoryDescription
primaryIdTypePAN | MOBILE | AADHAARENUMYesIdentifier Type for the borrower
primaryIdAlphanumericLength : 35YesBorrower unique identifier for the identifier type above
secondaryIdAlphanumericNo
categoryORGANIZATION | INDIVIDUALENUMYesCategory of the Borrower
nameStringMax Length : 50NoName of the borrower
contactDetailsArray ContactDetailsYesContactDetails for the borrower. If no data is there to be sent, an empty array block can be passed.
additionalIdentifiersArray AdditionalIdentifierNoAdditional identifier details for the borrower
platformDataArray PlatformDataNo
documentsArray DocumentYesAdditional documents related to the borrower. If no data is there to be sent, an empty array block can be passed.
urlStringMax Length : 1000No
extensibleDataJSONNoFor any new data that needs to be added

For Bhim for Lending case: GST TaxPayer Profile will be pulled from Search Tax payer API. The schema for GSTN profile can be found in the Search Tax Payer API published in https://developer.gst.gov.in/apiportal/common/others

Sample json

{
   "primaryId": "CPAA1234A",
   "primaryIdType": "PAN",
   "additionalIdentifiers": [],
   "name": "John doe",
   "category": "ORGANIZATION",
   "contactDetails": [
       {
           "type": "PRIMARY",
           "phone": "7777777777",
           "email": "johndoe@defenterprises",
           "address": {
               "co": "<care of>",
               "hba": "<House/Building/Apartment>",
               "srl": "<Street/Road/Lane>",
               "landmark": "",
               "als": "<Area/Locality/Sector>",
               "vtc": "<Village/Town/City>",
               "pincode": "",
               "po": "",
               "district": "",
               "state": "",
               "country": "",
               "uri": "<digital address>",
               "latitude": "",
               "longitude": ""
           }
       }
   ],
   "documents": []
}

Applicant

KeyTypeValidationMandatoryDescription
primaryIdTypePAN | MOBILE | AADHAARENUMYesIdentifier Type for the Applicant
primaryIdAlphanumericLength : 35YesApplicant unique identifier for the identifier type above
categoryORGANIZATION | INDIVIDUALENUMNoCategory of the Applicant
nameStringMax Length : 50NoName of the Applicant
relationshipWithBorrowerStringMax Length : 50NoRelationship of the applicant with Borrower
contactDetailsArray ContactDetailsNoContactDetails for the Applicant If no data is there to be sent, an empty array block can be passed.
additionalIdentifiersArray AdditionalIdentifierNoAdditional identifier details for the Applicant
documentsArray DocumentNoAdditional documents related to the Applicant. If no data is there to be sent, an empty array block can be passed.
urlStringNoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "primaryId": "<PAN NO.>",
   "primaryIdType": "PAN | <SOME VALID REGISTRY>",
   "additionalIdentifiers": [
       {
           "key": "",
           "value": ""
       }
   ],
   "name": "",
   "category": "ORGANISATION | INDIVIDUAL",
   "relationshipWithBorrower": "",
   "contactDetails": [
       {
           "type": "PRIMARY | OTHER",
           "phone": "",
           "email": "",
           "address": {
               "hba": "<House/Building/Apartment>",
               "srl": "<Street/Road/Lane>",
               "landmark": "",
               "als": "<Area/Locality/Sector>",
               "vtc": "<Village/Town/City>",
               "pincode": "",
               "po": "",
               "district": "",
               "state": "",
               "country": "",
               "uri": "<digital address>",
               "latitude": "",
               "longitude": ""
           }
       }
   ],
   "documents": [
       {
           "format": "PDF/EXCEL/PNG/JSON",
           "reference": "3c986a71-15c2-46a3-bf20-810ed203e06d",
           "source": "FIP | USER ",
           "sourceIdentifier": "",
           "type": "PAN | AADHAAR | DRIVING_LICENSE | PASSPORT",
           "isDataInline": "true/false",
           "data": "<Base64 encoded data>"
       }
   ]
}

Lender

KeyTypeValidityMandatoryDescription
primaryIdTypePAN | MOBILE | AADHAAR | FIUENUMYesIdentifier Type for the lender
primaryIdAlphanumericMin Length : 1
Max Length : 20
YesLender unique identifier for the identifier type above
categoryORGANIZATION | INDIVIDUALENUMYesCategory of the Lender
nameAlphanumericMax Length : 50YesName of the lender
additionalIdentifiersArray AdditionalIdentifierNoAdditional identifier details for the lender. If no data is there to be sent, an empty array block can be passed.
contactDetailsArray ContactDetailsYesContactDetails for the lender. If no data is there to be sent, an empty array block can be passed.
documentsArray DocumentYesAdditional documents related to the lender. If no data is there to be sent, an empty array block can be passed.
urlStringMax length : 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
       "primaryId": "AWWPA7645M",
       "primaryIdType": "PAN",
       "additionalIdentifiers": [],
       "name": "ABC Bank",
       "category": "ORGANIZATION",
       "contactDetails": [
           {
               "co": "<care of>",
               "type": "PRIMARY",
               "phone": "8888888888",
               "email": "abc@abcbank",
               "address": {
                   "hba": "<House/Building/Apartment>",
                   "srl": "<Street/Road/Lane>",
                   "landmark": "",
                   "als": "<Area/Locality/Sector>",
                   "vtc": "<Village/Town/City>",
                   "pincode": "",
                   "po": "",
                   "district": "",
                   "state": "",
                   "country": "",
                   "uri": "<digital address>",
                   "latitude": "",
                   "longitude": ""
               }
           }
       ],
       "documents": []
   }

ContactDetails

KeyTypeValidationsMandatoryDescription
typePRIMARY | OTHERENUMYesType of Contact. Whether primary or others.
descriptionStringMax Length : 1000NoDescription of the contact detail
phoneStringMin Length :10
Max Length : 15
YesPhone number
emailStringMin Length : 3
Max Length : 50
NoEmail address
addressAddressNoAddress
urlStringNoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample Json

{
   "type": "PRIMARY",
   "phone": "7777777777",
   "email": "johndoe@defenterprises",
   "address": {
       "co": "<Care of>",
       "hba": "<House/Building/Apartment>",
       "srl": "<Street/Road/Lane>",
       "landmark": "",
       "als": "<Area/Locality/Sector>",
       "vtc": "<Village/Town/City>",
       "pincode": "",
       "po": "",
       "district": "",
       "state": "",
       "country": "",
       "uri": "<digital address>",
       "latitude": "",
       "longitude": ""
   }
}

AdditionalIdentifier

KeyTypeValidationsMandatoryDescription
keyAlphanumericMin Length : 1
Max Length: 50
YesAdditional key related to the entity.
valueAlphanumericMin Length : 1
Max Length: 50
YesValue for the key in the context of the entity
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "key": "123488888888",
   "value": "AADHAAR"
}

Address

KeyTypeValidationsMandatoryDescription
coStringMax Length : 100NoCare of.
hbaStringMax Length : 255YesHouse/Building/Apartment
srlStringMax Length : 99YesStreet/Road/Lane
landmarkStringMax Length : 50NoLandmark
alsStringMax Length : 50NoArea/Locality/Sector
vtcStringMax Length : 50NoVillage/Town/City
pinCodeStringMax Length : 10YesPin Code
poStringMax Length : 10NoPost Office
districtStringMax Length : 50NoDistrict
stateStringMax Length : 50YesState
countryStringMax Length : 50YesCountry
latitudeStringMax Length : 50NoLatitude of the address
longitudeStringMax Length : 50NoLongitude of the address
urlStringMax Length : 1000NoDigital url for the address
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "hba": "<House/Building/Apartment>",
   "srl": "<Street/Road/Lane>",
   "landmark": "",
   "als": "<Area/Locality/Sector>",
   "vtc": "<Village/Town/City>",
   "pinCode": "",
   "po": "",
   "district": "",
   "state": "",
   "country": "",
   "url": "<digital address>",
   "latitude": "",
   "longitude": ""
}

Document

KeyTypeValidationsMandatoryDescription
sourceAA | FIP | FIU | FSR | USER | GSTNENUMYesSource system from where data is coming. Source can be from AA ecosystem or from USER
sourceIdentifierAlphanumericMin Length : 1
Max Length : 35
YesIf source is in AA ecosystem, sourceIdentifier is the identifier in central registry. In case of User, it will be his unique identifier
formatDOC | IMAGE | CSV | JSON | XMLENUMYesFormat of the data in documents
referenceString (UUID)Length : 35YesUnique identifier for a document which can be used by other objects for referencing a document. In case where isDataInline is false, reference number can be used to hit an external api to get the data.
typeGSTN_B2B_INVOICE | GSTN_PROFILE | PAN | AADHAAR | DRIVING_LICENSE | PASSPORT | OTHERENUMYesExpandable enum. Includes fiTypes in AA ecosystem and any additional type of documents that can be added to the system later
isDataInlineBooleanYesIndicates whether the data is actually present in the document block. If Yes, data field contains base 64 encoded version of the data.
dataStringMin Length : 1YesBase64 encoded string

Sample json including GSTN data about Borrower

{
   "source": "GSTN",
   "sourceIdentifier": "GSTN",
   "format": "JSON",
   "reference": "docref12",
   "type": "GST_PROFILE",
   "isDataInline": true,
   "data": "eyJzdGpDZCI6IkFQMDAzIiwibGdubSI6Ik1TIENPUlBPUkFUSU9OIiwic3RqIjoiQkNQIEtPRElLT05EQSIsImR0eSI6IlJlZ3VsYXIiLCJjeGR0IjoiIiwiZ3N0aW4iOiIwNUFCTlRZMzI5MFA4WkEiLCJuYmEiOlsiQm9uZGVkIFdhcmVob3VzZSIsIkVPVSAvIFNUUCAvIEVIVFAiLCJGYWN0b3J5IC8gTWFudWZhY3R1cmluZyIsIklucHV0IFNlcnZpY2UgRGlzdHJpYnV0b3IgKElTRCkiLCJMZWFzaW5nIEJ1c2luZXNzIl0sImxzdHVwZHQiOiIwNS8wMS8yMDE3IiwicmdkdCI6IjA1LzA1LzIwMTciLCJjdGIiOiJGb3JlaWduIExMUCIsInN0cyI6IlByb3Zpc2lvbmFsIiwiY3RqQ2QiOiJBUDAwNCIsImN0aiI6IkJDUCBUSFVNTUFLVU5UQSIsInRyYWRlTmFtIjoiQUxUT04gUExBU1RJQyBQUklWQVRFIExURCIsImFkYWRyIjpbeyJhZGRyIjp7ImJubSI6IkVMUEhJTlNUT05FIEJVSUxESU5HIiwic3QiOiIxMCwgVkVFUiBOQVJJTUFOIFJPQUQiLCJsb2MiOiJGT1JUIiwiYm5vIjoiMTAiLCJzdGNkIjoiUmFqYXN0aGFuIiwiZmxubyI6IjFTVCBGTE9PUiIsImx0IjoiNzQuMjE3OSIsImxnIjoiMjcuMDIzOCIsInBuY2QiOiI0MDAwMDEifSwibnRyIjpbIldob2xlc2FsZSBCdXNpbmVzcyJdfV0sInByYWRyIjp7ImFkZHIiOnsiYm5tIjoiS0FUR0FSQSBIT1VTRSIsInN0IjoiMTUsIEwgSkFHTU9IQU5EQVMgTUFSRyIsImxvYyI6Ik1BTEFCQVIgSElMTCIsImJubyI6IjUiLCJzdGNkIjoiTWFoYXJhc2h0cmEiLCJmbG5vIjoiNFRIIEZMT09SIiwibHQiOiI3NC4yMTc5IiwibGciOiIyNy4wMjM4IiwicG5jZCI6IjQwMDAwNiJ9LCJudHIiOlsiV2hvbGVzYWxlIEJ1c2luZXNzIl19fQ"
}

The schema for GSTN profile can be found in the Search Tax Payer API published in https://developer.gst.gov.in/apiportal/common/others

Collateral

This block describes the credit instruments that you are using to raise a loan request. In Invoice financing, this block will capture invoices. For taking a loan against a house, this will have home registration document details.

KeyTypeValidationsMandatoryDescription
collateralPrimaryIdAlphanumericLength : 35YesPrimary Identifier for the collateral. Generated as collateralPrimaryIdType_collaetralPrimaryId
collateralPrimaryIdTypeGST_INVOICE | VIN | ENUMYesExpandable ENUM. Type of collateral source. Will be Invoice in case of invoice based lending, vehicle identification number (VIN) for vehicle as collateral
descriptionStringMax Length : 1000NoDescription of the collateral
typeGST_INVOICE | VEHICLE | HOMEYesType of collateral.
additionalIdentifiersArray AdditionalIdentifierYesAdditional identifier for the collateral. If no data is there to be sent, an empty array block can be passed.
valuationValuationNoValuation details of the collateral including value, source etc
partiesArray PartyYesParties involved in the collateral. In case of home loan agreement, this can hold details of current owner and previous owner. If no data is there to be sent, an empty array block can be passed.
documentsArray DocumentYesAdditional documents related to the collateral. If no data is there to be sent, an empty array block can be passed.
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
           "collateralPrimaryId": "INVOICE_<GSTIN>_<INVOICENUM>",
           "collateralPrimaryIdType": "GST_INVOICE | VIN <SOME VALID REGISTRY>",
           "additionalIdentifiers": [
               {
                   "key": "",
                   "value": ""
               }
           ],
           "valuation": {
               "value": "",
               "currency": "",
               "date": "",
               "source": "GSTN"
           },
           "parties": [
               {
                   "primaryId": "<PAN NO.>",
                   "primaryIdType": "PAN | <SOME VALID REGISTRY>",
                   "additionalIdentifiers": [
                       {
                           "key": "",
                           "value": ""
                       }
                   ],
                   "name": "",
                   "category": "ORGANISATION | INDIVIDUAL",
                   "relationshipWithCollateral": "",
                   "contactDetails": [
                       {
                           "type": "PRIMARY | OTHER",
                           "phone": "",
                           "email": "",
                           "address": {
                               "hba": "<House/Building/Apartment>",
                               "srl": "<Street/Road/Lane>",
                               "landmark": "",
                               "als": "<Area/Locality/Sector>",
                               "vtc": "<Village/Town/City>",
                               "pincode": "",
                               "po": "",
                               "district": "",
                               "state": "",
                               "country": "",
                               "uri": "<digital address>",
                               "latitude": "",
                               "longitude": ""
                           }
                       }
                   ],
                   "documents": [
                       {
                           "format": "JSON",
                           "reference": "3c986a71-15c2-46a3-bf20-810ed203e06d",
                           "source": "FIP | USER ",
                           "sourceIdentifier": "",
                           "type": "",
                           "isDataInline": true,
                           "data": "<Base64 encoded data>"
                       }
                   ]
               }
           ],
           "type": "GST_INVOICE",
           "documents": [
               {
                   "format": "JSON",
                   "reference": "3c986a71-15c2-46a3-bf20-810ed203e06d",
                   "source": "GSTN",
                   "sourceIdentifier": "GSTN",
                   "type": "GSTN_B2B_INVOICE",
                   "isDataInline": true,
                   "data": "eyJjdGluIjoiMDFBQUJDRTIyMDdSMVo1IiwiY2ZzIjoiWSIsImludiI6W3siY2hrc3VtIjoiQkJVSUJVSVVJSktLQkpLR1VZRlRGR1VZIiwidXBkYnkiOiJTIiwiaW51bSI6IlMwMDg0MDAiLCJpZHQiOiIyNC0xMS0yMDE2IiwidmFsIjo3MjkyNDguMTYsInBvcyI6IjA2IiwicmNocmciOiJOIiwiZXRpbiI6IjAxQUFCQ0U1NTA3UjFaNCIsImludl90eXAiOiJSIiwiY2ZsYWciOiJOIiwiZGlmZl9wZXJjZW50IjowLjY1LCJvcGQiOiIyMDE2LTEyIiwiaXRtcyI6W3sibnVtIjoxLCJpdG1fZGV0Ijp7InJ0Ijo1LCJ0eHZhbCI6MTAwMDAsImlhbXQiOjMyNSwiY2FtdCI6MCwic2FtdCI6MCwiY3NhbXQiOjEwfX1dfV19"
               }
           ]
       }

The schema for GSTN invoice can be found in the ANX1-GetB2B API published in https://developer.gst.gov.in/apiportal/taxpayer/newreturns .

However, for the first phase, we might actually be using the old returns api - GSTR1 - Get B2B Invoices. The documents.data field on decoding gives the B2B invoices return.

Cred Block

KeyTypeValidationsMandatoryDescription
typeOTPENUMYesType of credential used for verification
dataOTPBlockYesCredential details specific to the the type
extensibleDataJSONNoFor any new data that needs to be added

OTPBlock

KeyTypeValidationsMandatoryDescription
appTokenStringMax Length : 100NoAcknowledgement block indicating the receipt and status of request
otpSessionKeyStringLength : 35NootpSession created for verifying the OTP sent by the borrower
maskedPhoneNumberStringMax Length : 15NoPhone number linked to the disbursement account obtained from the AA bank account statements
urlStringMax Length : 1000No
extensibleDataJSONNoPair of key values of adding custom fields
otpNumericLength : 6NoOne time numeric password generated by lender sent to the registered mobile number of the disbursement account holder
statusINVALID_SESSION | INCORRECT_OTP | SUCCESSYesField captures the status of verify OTP

LoanDetail

KeyTypeValidationsMandatoryDescription
loanIdAlphanumericLength : 35YesUUID for loan. Created by lender
termsLoanTermsYesTerms of the loan

Valuation

KeyTypeValidationMandatoryDescription
valueStringMax Length : 20NoValue of the collateral. In case of invoice this can have the invoice value. 2 digits precision
descriptionStringMax Length : 1000NoDescription of the valuation
dateDateMax Length : 20NoDate when the valuation of collateral was done
currencyCurrencyTypeMax Length : 20NoCurrency
sourceGSTN | OTHERSENUMNoExpandable ENUM. Source of the valuation.
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
               "value": "20000",
               "currency": "INR",
               "date": "2018-12-06",
               "source": "GSTN"
}

Party

KeyTypeValidationsMandatoryDescription
primaryIdTypePAN | MOBILE | AADHAAR | FIUENUMYesIdentifier Type for the party
primaryIdAlphanumericMin Length : 1
Max Length : 20
YesParty unique identifier for the identifier type above
descriptionStringMax Length: 1000NoDescription of the party
categoryORGANIZATION | INDIVIDUALENUMYesCategory of the party
nameAlphanumericMax Length : 50YesName of the party
relationshipWithCollateralAlphanumericMax Length : 50YesAssociation with collateral. In case of invoice the 2 parties involved would be the buyer and seller
additionalIdentifiersArray AdditionalIdentifierNoAdditional identifier details for the party. If no data is there to be sent, an empty array block can be passed.
contactDetailsArray ContactDetailsYesContactDetails for the party. If no data is there to be sent, an empty array block can be passed.
documentsArray DocumentYesAdditional documents related to the party. If no data is there to be sent, an empty array block can be passed.
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample Json

{
   "primaryId": "<PAN NO.>",
   "primaryIdType": "PAN",
   "additionalIdentifiers": [
       {
           "key": "",
           "value": ""
       }
   ],
   "name": "",
   "category": "INDIVIDUAL",
   "relationshipWithCollateral": "",
   "contactDetails": [
       {
           "type": "PRIMARY",
           "phone": "",
           "email": "",
           "address": {
               "hba": "<House/Building/Apartment>",
               "srl": "<Street/Road/Lane>",
               "landmark": "",
               "als": "<Area/Locality/Sector>",
               "vtc": "<Village/Town/City>",
               "pincode": "",
               "po": "",
               "district": "",
               "state": "",
               "country": "",
               "uri": "<digital address>",
               "latitude": "",
               "longitude": ""
           }
       }
   ],
   "documents": [
       {
           "format": “PNG",
           "reference": "3c986a71-15c2-46a3-bf20-810ed203e06d",
           "source": "USER",
           "sourceIdentifier": "USER",
           "type": "PAN",
           "isDataInline": true,
           "data": "<Base64 encoded data>"
       }
   ]
}

Charges

KeytypeValidationsMandatoryDescription
prepaymentChargeDetailsNoDetails of the charges levied for prepayment of loan
bounceChargeDetailsNoDetails of the charges levied when a repayment attempt by the borrower is not honored by bank. Eg: failure of a mandate execution
latePaymentChargeDetailsNoDetails of the charges levied when the borrower makes a late payment
processingChargeDetailsNoProcessing fees charged by the lender

SampleJson

{
   "prepayment": {
       "chargeType": "RATE_BASED",
       "data": {
           "rate": "6",
           "applicableParameter": "TOTAL_LOAN_AMOUNT"
       }
   },
   "bounce": {
       "chargeType": "FIXED_AMOUNT",
       "data": {
           "amount": "3000.00"
       }
   },
   "latePayment": {
       "chargeType": "FIXED_AMOUNT",
       "data": {
           "amount": "3000.00"
       }
   },
   "processing": {
       "chargeType": "FIXED_AMOUNT",
       "data": {
           "amount": "3000.00"
       }
   }
}

ChargeDetails

KeytypeValidationsMandatoryDescription
chargeTypeFIXED_AMOUNT | RATE_BASEDENUMYesThis field indicates whether the penalty is fixed or varies
dataJsonYesThis object captures the details of the charges
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

The fields that can come inside data Json are the below.

rateStringMax Length : 10NoAnnualized Rate of interest charged as penalty. 2 digits precision. Applicable only when type= RATE_BASED
amountStringMax Length : 20NoFixed penalty charged
descriptionStringMax Length : 500NoA brief description of how the penalty charges will be applied
urlStringMax Length : 1000NoA link to the lender’s page explaining the calculation of penalty
applicableParameterTOTAL_LOAN_AMOUNT | OUTSTANDING_PAYABLE_AMOUNT| EMI | PREPAYMENT_PRINCIPALENUMNoThe parameter on which rate is applied to arrive at the rate based charge. For example : If rate is 6% and applicable parameter is TOTAL_LOAN_AMOUNT, penalty = 0.06*TOTAL_LOAN_AMOUNT

Sample JSON

{
     "chargeType": "RATE_BASE,
     "data": {
          "rate": "6",
          "applicableParameter": "TOTAL_LOAN_AMOUNT"
     }
}

LoanTerms

KeytypeValidationsMandatoryDescription
requestedAmountStringMin Length : 1
Max Length : 20
YesAmount . 2 digits precision
descriptionStringMax Length : 1000NoDescription of the loan terms
currencyCurrencyTypeMin Length : 1
Max Length : 20
YesCurrency
sanctionedAmountStringMin Length : 1
MaxLength : 20
NoLoan Amount Approved by lender
interestTypeFIXED | FLOATINGMax Length : 20NoFlag indicating if the interest rate is fixed or floating
interestRateStringMax Length : 20NoInterest Rate for the loan. 2 digits precision
interestAmountStringMax Length : 20NoInterest Amount for the duration specified in tenure
totalAmountStringMax Length : 20NoTotal amount for repaymen
tenureLoanTenureNoTenure details of the loan
legalAgreementLoan AgreementNoLoan agreement
documentsArray DocumentNoAdditional documents regarding the loan terms
chargesChargesNoPenalties levied for issues with repayments
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample JSON

{
       "requestedAmount": "50000.00",
       "currency": "INR",
       "sanctionedAmount": "5000.00",
       "interestType": "FIXED",
       "interestRate": "6.50",
       "tenure": {
           "duration": "3",
           "unit": "MONTH"
       },
       "legalAgreement": {
           "type": "TEXT",
           "data": "<Base64 Encoded Data>"
       },
       "documents": [],
   	"charges": {
       	"prepayment": {
           		"type": "RATE_BASED",
           		"rate": "6.00",
           		"applicableParameter": "TOTAL_LOAN_AMOUNT"
       	},
       	"bounce": {
           		"type": "FIXED_AMOUNT",
           		"amount": "3000.00"
       	},
       	"latePayment": {
           		"type": "FIXED_AMOUNT",
           		"amount": "3000.00"
       	},
       	"processing": {
           		"type": "FIXED_AMOUNT",
           		"amount": "3000.00"
       	}
   	}
   }

LoanAgreement

KeytypeValidationsMandatoryDescription
typeTEXT | URLENUMYesIndicates whether the agreement is shared directly as text or needs to be fetched from a url
dataStringMin Length : 1YesBase64 encoded string.
If type = text, this field will have the loan agreement in base 64 encoded format.
If type = url, this field will have base 64 encoded url from where doc can be fetched.

CreditScoreType

KeytypeValidationMandatoryDescription
valueStringMin Length : 1
Max Length : 20
YesCredit score given for the borrower by the LSP. 0-900 range
sourceLSP | PLATFORMSENUMYesSource of the credit score. Can be LSP in case of FLDG. If it is not FLDG we still want to send credit score. (Maybe swiggy wants to send the score)
sourceIdentifierStringMin Length : 1
Max Length : 35
YesIdentifier of the source. Eg. SWIGGY for Restaurants
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "value": "800",
   "sourceType": "LSP",
   "source": "SWIGGY"
}

Guarantor

KeytypeValidationsMandatoryDescription
primaryIdTypePAN | MOBILE | AADHAARENUMYesIdentifier Type for the guarantor
primaryIdAlphanumericLength : 35Yesguarantor unique identifier for the identifier type above
descriptionStringMax Length : 1000NoDescription of the guarantor and his involvement in the loan
categoryORGANIZATION | INDIVIDUALENUMYesCategory of the guarantor
nameStringMax Length : 50NoName of the guarantor
relationshipWithBorrowerStringMax Length : 50NoRelationship with the borrower
contactDetailsArray ContactDetailsYesContactDetails for the guarantor. If no data is there to be sent, an empty array block can be passed.
additionalIdentifiersArray AdditionalIdentifierNoAdditional identifier details for the guarantor
documentsArray DocumentYesAdditional documents related to the guarantor. If no data is there to be sent, an empty array block can be passed.
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "primaryId": "CPAA1234A",
   "primaryIdType": "PAN",
   "additionalIdentifiers": [],
   "name": "John doe",
   "relationshipWithBorrower": "Father",
   "category": "ORGANIZATION",
   "contactDetails": [
       {
           "type": "PRIMARY",
           "phone": "7777777777",
           "email": "johndoe@defenterprises",
           "address": {
               "co": "<care of>",
               "hba": "<House/Building/Apartment>",
               "srl": "<Street/Road/Lane>",
               "landmark": "",
               "als": "<Area/Locality/Sector>",
               "vtc": "<Village/Town/City>",
               "pincode": "",
               "po": "",
               "district": "",
               "state": "",
               "country": "",
               "uri": "<digital address>",
               "latitude": "",
               "longitude": ""
           }
       }
   ],
   "documents": []
}

RejectionDetail

KeytypeValidationsMandatoryDescription
reasonFRAUD | DOC_IRREGULARITIES | LOW_CREDIT_SCORE | OTHERSENUMYesReason why the lender has decided not to make a loan offer to the borrower
descriptionStringMin length : 1
Max Length : 1000
YesDetailed description of the reason for rejection
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "reason": "LOW_CREDIT_SCORE",
   "description": "Credit score below 600"
}

Reference

This object is used when a reference needs to be made to another object that is sent as part of the request / response. For example, when the lender sends an Action Required block, it might refer to a document in the documents section

KeytypeValidationsMandatoryDescription
objectStringMin Length : 1
Max Length : 20
YesName of the object in the request/reference to which the reference is made
valueStringMin Length : 1
Max Length : 35
YesReference number within the referred object

Sample json

{
   "object": "documents",
   "value": "INVOICE_GSTN_INV2011"
}

ActionRequired

KeytypeValidationsMandatoryDescription
actionTypeADD_DOCUMENT | RESUBMIT_DOCUMENT | OTHERENUMYesType of action expected from the borrower
descriptionStringMin Length : 1
Max Length : 99
YesDetailed description of the expected action
referenceReferenceNoReference to any documents uploaded as part of the loan request indicating the document where action is required
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "actionType": "ADD_DOCUMENT",
   "description": "DL number not visible",
   "reference": {
       "object": "documents",
       "value": ""
   }
}

Ack

Standard response block obtained for an Asynchronous API call.

KeytypeValidationsMandatoryDescription
errorStringMin Length : 1
Max Length : 35
YesErrors in the current request received.If no errors are found, error = 0. For example, if a mandatory attribute is missing, error code should capture that
traceIdAlphanumericMin Length : 1
Max Length : 35
YesMessage identifier-used to correlate between the request and response. The unique identifier created by the originator of the message and will be used to correlate the response with the original request
timestampISODateTime
YYYY-MM-DDThh:mm:ssZ+/-hh:mm (eg 1997-07-16T19:20:30+05:30) where; YYYY = four-digit year MM = two-digit month (01=January, etc.) DD = two-digit day of month (01 through 31) hh = two digits of hour (00 through 23) (am/pm NOT allowed) mm = two digits of minute (00 through 59) ss = two digits of second (00 through 59) Z +/- hh:mm = time zone designator (Z) followed by time zone difference from GMT in hours and minutes. THIS IS OPTIONAL. If not provided, it is assumed to be IST (+5.30)
Min Length : 1
Max Length : 255
YesTime of request from the creator of the message. API request time stamp. Since timestamp plays a critical role, it is highly recommended that devices are time synchronized with a time server.

Sample json

{
   "error": "0",
   "traceId": "e8cc6822-d4bb-4eb1-9e1b-4996fbff8acb",
   "timestamp": "2018-12-06T11:39:57.153Z"
}

Offer

KeytypeValidationsMandatoryDescription
idAlphanumericMin Length : 1
Max Length : 35
YesUnique identifier for the offer in the lending system
descriptionStringMax Length : 1000NoA short description of the offer.
validTillISODateTimeMin Length : 1
Max Length : 255
YesTime till which the offer from the lender is available
termsLoanTermsYesDetails about the terms of the loan offer
disbursementDisbursementYesDetails about the disbursement provided by lender.
repaymentRepaymentYesDetails about the repayment plans provided by lender.
documentsArray DocumentNoAny other additional documents provided by the lender as part of the offer. If no data is there to be sent, an empty array block can be passed.
urlStringMax Length: 1000NoFor any new data that needs to be passed as a linkFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
   "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "validTill": "2018-12-06T00:00:00.000Z",
   "terms": {
       "requestedAmount": "50000.00",
       "currency": "INR",
       "sanctionedAmount": "50000.00",
       "interestType": "FIXED",
       "interestRate": "6.00",
       "tenure": {
           "duration": "3",
           "unit": "MONTH"
       },
       "legalAgreement": {
           "type": "TEXT",
           "data": "<Base64 Encoded Data>"
       },
       "charges": {
           "prepayment": {
               "chargeType": "RATE_BASED",
               "data": {
                   "rate": "6.00",
                   "applicableParameter": "TOTAL_LOAN_AMOUNT"
               }
           },
           "bounce": {
               "chargeType": "FIXED_AMOUNT",
               "data": {
                   "amount": "3000.00"
               }
           },
           "latePayment": {
               "chargeType": "FIXED_AMOUNT",
               "data": {
                   "amount": "3000.00"
               }
           },
           "processing": {
               "chargeType": "FIXED_AMOUNT",
               "data": {
                   "amount": "3000.00"
               }
           }
       }
   },
   "disbursement": {
       "plans": [
           {
               "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
               "autoDisbursement": false,
               "scheduleType": "ONE_TIME",
               "amount": "10000.00"
           }
       ],
       "accountDetails": {
           "accountDataType": "ACCOUNT",
           "data": {
               "accountType": "CURRENT",
               "maskedAccountNumber": "XXXXXXXXX9090"
           }
       }
   },
   "repayment": {
       "plans": [
           {
               "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
               "autoRepayment": "Y",
               "scheduleType": "ONE_TIME",
               "amount": "10000.00"
           }
       ],
       "methods": [
           {
               "type": "EMANDATE_UPI",
               "data": {
                   "refNumber": "",
                   "amount": "50000.00",
                   "amountType": "MAX",
                   "activeFrom": "2020-01-01",
                   "expiryDate": "",
                   "destinationAccount": {
                       "accountDataType": "ACCOUNT",
                       "data": {
                           "accountType": "CURRENT",
                           "accountIFSC": "IKCC0009",
                           "maskedAccountNumber": "XXXXXXXX9090",
                           "accountNumber": "1112090999090"
                       }
                   },
                   "sourceAccount": {
                       "accountDataType": "VPA",
                       "data": {
                           "accountType": "CURRENT",
                           "accountIFSC": "IKCC0009",
                           "maskedAccountNumber": "XXXXXXXX9090",
                           "accountNumber": "1112090999090"
                       }
                   }
               }
           }
       ]
   }
}

ChosenRepayment

KeytypeValidationsMandatoryDescription
planPaymentPlanYesRepayment plan chosen by borrower for the loan
methodPaymentMethodNoCurrent Repayment Method set by the borrower

PaymentPlan

KeytypeValidationsMandatoryDescription
idAlphanumericMin Length : 1
Max Length : 35
YesUnique id for the repayment plan in the lender system
titleStringMax Length : 100NoTitle for the repayment plan
shortDescriptionStringMax Length : 100NoShort description for the repayment plan
descriptionStringMax Length : 2000NoDetailed description of the payment plan
paymentUrlStringMax Length : 1000NoUrl of the payment page provided by the lender
automaticBooleanMin Length : 1
Max Length : 1
YesFlag indicating whether payment is automatic or user initiated
payNowAllowedBooleanNoFlag indicates if the borrower can make an immediate payment with this repayment plan
editPlanAllowedBooleanNoThis flag indicates if the configurations of the current repayment plan can be changed by the borrower
changeMethodAllowedchangeMethodAllowedNoThis field indicates if the borrower can choose a different payment method for the plan
scheduleTypeONE_TIME | RECURRING | AS_PRESENTEDENUMYesType of schedule - can be one time, as_presented or recurring
frequencyWEEKLY | MONTHLY | QUARTERLY | HALF YEARLY | YEARLYENUMNoIn case of a recurring payment, this field indicates how often the payment is disbursed
noOfInstallmentsAlphanumericMax Length : 10YesNumber of installments for the chosen repayment plan. Will be 1 for ONE TIME schedule type
tenureLoanTenureNoTenure associated with the repayment plan. This value will be less than or equal to the tenure in loan terms.
principalAlphanumericMax Length : 20NoPrincipal. Upto 2 digits precision
interestAmountAlphanumericMax Length : 20NoInterest component for the duration specified in plan. Upto 2 digits precision
penaltypenaltyMax Length : 20NoPenalty component for the duration specified in loan. Upto 2 digits precision
startDateDateNoThe first date on which the borrower chooses to make payment/wishes to get the disbursement credited.
statusACTIVE | INACTIVE | PENDING_AUTHENUMNoFlag indicating if the plan is active or inactive
totalAmountStringMin Length : 1
Max Length : 20
YesAmount to be repaid as per the payment plan. 2 digits precision
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample Json

{
   "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "automatic": false,
   "scheduleType": "RECURRING",
   "frequency": "MONTHLY",
   "tenure": {
   	"duration": "1",
   	"unit": "MONTH"
   },
   "totalAmount": "5000.00"
}

LoanTenure

KeytypeValidationsMandatoryDescription
durationStringMin length : 1
Max Length : 10
YesDuration of the loan amount
unitDAY | MONTH | YEARENUMYesUnit in which the loan duration is mentioned
{
   "duration": "1",
   "unit": "MONTH"
}

LoanTermsHistory

KeytypeValidationsMandatoryDescription
interestStringMin Length : 1
Max Length : 10
YesLoan interest rate as on the effective date. 2 digits precision
tenuretenureMin Length : 1
MaxLength : 20
YesTenure of the loan amount as on the effective date
effectiveDateDateMin Length : 1
Max Length : 10
YesDate on which the interest and tenure is effective

Sample Json

{
       "interest": "18",
       "tenure": {
           "duration": "1",
           "unit": "MONTH"
       },
       "effectiveDate": "2020-01-01"
   }

Repayment

KeytypeValidationsMandatoryDescription
plansArray PaymentPlanYesRepayment plans provided by lender for the loan

Disbursement

KeytypeValidationsMandatoryDescription
plansArray PaymentPlanYesDisbursement plans provided by lender for the loan
accountDetailsArray AccountDetailsNoAccount where the amount will be disbursed by the lender.

ChosenDisbursement

KeytypeValidationsMandatoryDescription
planPaymentPlanYesDisbursement plans selected for the loan
accountDetailsAccountDetailsNoAccount where the amount will be disbursed by the lender.

Payment

KeytypeValidationsMandatoryDescription
idAlphanumericLength : 35Length : 35UUID for the payment request. Generated by LSP
descriptionStringLength : 500Length : 500A short description of the payment
dateTimestampMin Length : 1
Max Length : 20
NoDate and time when the payment transaction is done
principalStringMin Length : 1
Max Length : 20
NoPrincipal paid by the borrower. 2 digits precision
interestAmountStringMin Length : 1
Max Length : 20
NoInterest paid by the borrower. 2 digits precision
feeStringMin Length : 1
Max Length : 20
NoFees paid by the borrower. 2 digits precision
penaltyStringMin Length : 1
Max Length : 20
NoPenalty paid by the borrower. 2 digits precision
totalAmountStringMin Length : 1
Max Length : 20
NoTotal amount paid by borrower. 2 digit precision
installmentNumberStringMax Length : 10NoThe installment which is being currently paid
statusSUCCESS | FAILURE | PROCESSING | PENDING_AUTHENUMNoStatus of the repayment
useSavedPaymentOptionBooleanNoIndicates whether the payment needs be made with the savedPaymentOption. Incase where it is a disbursement, this flag being set disburses amount to the pre-selected account. In case of repayment, this flag being set causes repayment using already set payment method
paymentMethodTypeEMANDATE_UPI | NETBANKING | UPI | ENACH | DEBIT_CARD | CREDIT_LINENoPayment method used for the transaction. To be populated when payment is done
paymentUrlStringMax Length : 1000NoUrl for the payment page
txnRefNoStringMin Length : 1
Max Length : 100
NoReceipt no of the transactions
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample Json

{
       "totalAmount": "5000.00",
       "date": "2020-10-10",
       "status": "SUCCESS",
       "installmentNumber": "1",
       "txnRefNo": "004618602124",
       "paymentId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
}

Transaction

KeytypeValidationsMandatoryDescription
dateTimestampYesTime when the transaction is carried out
narrationStringMax Length : 200YesNarration as it appears in the bank statement
txnRefNoStringMax Length : 20YesReference number for the transaction
amountAlphanumericMax Length : 20YesTransaction Amount. Upto 2 digits precision
typeDEPOSIT | WITHDRAWALENUMYesDEPOSIT for repayment transactions and WITHDRAWAL for disbursement transactions
closingBalanceAlphanumericAlphanumericYesClosing balance in the account after the transaction
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample json

{
           "date": "25-01-2020",
           "narration": "Repayment of Loan no : xxxxxxx9090",
           "txnRefNo": "004618602124",
           "amount": "50000.00",
           "type": "DEPOSIT",
           "closingBalance": "50000.00"
}

Dispute

KeytypeValidationsMandatoryDescription
idAlphanumericMax Length : 35NoUUID for dispute. Generated by lender
descriptionStringMin Length : 1
Max Length : 256
NoDetailed description of the complaint code raised by borrower
urlStringMax Length: 1000NoLender url where dispute details can be seen / updated
statusNEW | PROCESSING | NEEDMORE INFO | RESOLVED | CLOSEDENUMNoCurrent status of the dispute
extensibleDataJSONNoFor any new data that needs to be added

AccountDetails

KeytypeValidationsMandatoryDescription
idAlphanumericMax Length : 35NoUnique id. Mandatory if object is coming from lender
descriptionStringMax Length : 1000NoDescription of the account
statusACTIVE | INACTIVEENUMNoThis field captures the status of whether the account has been linked to a loan or not
accountDataTypeACCOUNT | VPAENUMYesThis suggests what kind of data is expected for account details in the data object
dataAccountDetailsDataYesAccount details specific to the accountDataType
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

AccountDetailsData

KeytypeValidationsMandatoryDescription
accountTypeCURRENT | SAVINGS | OVERDRAFTENUMNoType of the account
accountIFSCStringMax Length : 20NoIFSC code of the account
accountNumberStringMax Length : 20NoAccount Number
vpaStringMax Length : 50NoVirtual Payment Address
maskedAccountNumberStringNoMasked account details

Sample Json

{
      "accountType": "CURRENT",
      "maskedAccountNumber": "XXXXXXXXX9090"
}

PaymentMethod

KeytypeValidationsMandatoryDescription
idAlphanumericLength : 35YesUnique id created in the lender system for the repaymentMethod.
descriptionStringMax Length : 1000NoDescription of the payment method.
typeEMANDATE_UPI | ELIEN | ENACH | ANYENUMNoType of repayment method chosen
isActiveBooleanYesIs the loan/credit line active for payment? TRUE, if Active
dataJsonNoParameters for the repayment method which varies based on type.
statusINACTIVE, ACTIVE, CANCELLED, PAUSEDENUMYesStatus of the repaymentMethod in the lender system
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

For type = EMANDATE_UPI , data object will have the structure of Mandate Domain Object.

Consent

KeytypeValidationsMandatoryDescription
vuaStringMin Length : 3
Max Length : 50
NoCustomer unique identifier created by the AA. Example : user@onemoney.
descriptionStringMax Length : 1000NoDescription of the consent
lspInfoLSPInfoNoThis information is supposed to be passed to AA so that they can write custom logic for handling the consent
consentFetchTypePERIODIC | ONETIMEENUMNoPeriodicity for the consent data fetch
isAggregationEnabledBooleanNoFlag indicating whether the consents need to be aggregated
consentAggregationIdAlphanumericIds are of length 35 eachNoThis is an id generated by LSP which is passed on to AA to tell the AA how to aggregate all the consent requests from all the lenders.
consentHandleStringLength : 36NoConsent handles created by the AA for the lender’s request. This field will be filled when status is PENDING
consentStatusREADY | PENDING | FAILEDENUMNoStatus of the consent
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

LspInfo

KeytypeValidationsMandatoryDescription
lspIdStringLength: 35YesUnique identifier for the lsp in the ecosystem
versionversionLength: 35YesVersion of the lsp
appNameStringLength: 35YesYes
urlStringMax Length: 1000NoFor any new data that needs to be passed as a link
extensibleDataJSONNoFor any new data that needs to be added

Sample Json

"lspInfo": {
     "lspId": "<AA can identify the LSP based on this>",
	"version": "<version of LSP>",
	"appName": "<Package name of the app>"
   }