API Specification

The payloads under each of the APIs are the payloads that are needed for the BHIM4 Lending use-case. The objects defined however are more generic and can cater to a wider set of lending use-cases. More details regarding the objects and the specific fields under each can be found under the Domain Object Specification section.

Loan Application APIs

1) Create Loan Applications Request

HTTP Verb - POST
API Endpoint - /v3/loanApplication/createLoanApplicationsRequest**

This API is called by the LSP to create loan applications in the lender system. The LSP sends all the data about the borrower in this request.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanApplications

Array
LoanApplication

Yes

Array of LoanApplications

LoanApplication (Following shows fields of LoanApplication that matter in this API)

Key

type

Validations

Mandatory

Description

createdDate

ISODateTime

Yes

Time when the loan application was created

loanApplicationId

Alphanumeric

Length : 35

Yes

UUID for the loan application. Generated by LSP

type

CASHFLOW | PERSONAL | HOME | VEHICLE | BUSINESS

ENUM

Yes

Expandable Enum. Captures the type of loan. Will be Cash Flow for invoice based loans.

borrower

Borrower

Yes

Details of the Borrower

collaterals

Array Collateral

Yes

Details 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.

guarantors

Array Guarantors

Yes

List of guarantors that the borrowers have for the loan. If no data is there to be sent, an empty array block can be passed.

applicants

Array Applicant

Yes

List of applicants for the loan. If no data is there to be sent, an empty array block can be passed

terms

LoanTerms

Yes

Terms of loan agreement

description

String

Max Length : 1000

No

A short description of the loan application

url

String

Max Length : 1000

No

For any new data that needs to be passed as a link

extensibleData

JSON

No

For any new data that needs to be added

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
  "metadata": {
      "version": "1.0.0",
      "timestamp": "2018-12-06T11:39:57.153Z",
      "traceId": "a8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
      "orgId": "LSP123"
  },
  "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
  "loanApplications" : [
       {
           "createdDate": "2020-03-01T00:00:00Z",
           "loanApplicationId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "type": "CASHFLOW",
           "borrower": {
               "primaryId": "CPAA1234A",
               "primaryIdType": "PAN",
               "additionalIdentifiers": [],
               "name": "John doe",
               "category": "ORGANIZATION",
               "contactDetails": [
                   {
                       "type": "PRIMARY",
                       "phone": "7777777777",
                       "email": "[email protected]",
                       "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": [
                   {
                       "format": "JSON",
                       "reference": "b8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
                       "source": "GSTN",
                       "sourceIdentifier": "GSTN",
                       "type": "GSTN_PROFILE",
                       "isDataInline": true,
                       "data": "eyJzdGpDZCI6IkFQMDAzIiwibGdubSI6Ik1TIENPUlBPUkFUSU9OIiwic3RqIjoiQkNQIEtPRElLT05EQSIsImR0eSI6IlJlZ3VsYXIiLCJjeGR0IjoiIiwiZ3N0aW4iOiIwNUFCTlRZMzI5MFA4WkEiLCJuYmEiOlsiQm9uZGVkIFdhcmVob3VzZSIsIkVPVSAvIFNUUCAvIEVIVFAiLCJGYWN0b3J5IC8gTWFudWZhY3R1cmluZyIsIklucHV0IFNlcnZpY2UgRGlzdHJpYnV0b3IgKElTRCkiLCJMZWFzaW5nIEJ1c2luZXNzIl0sImxzdHVwZHQiOiIwNS8wMS8yMDE3IiwicmdkdCI6IjA1LzA1LzIwMTciLCJjdGIiOiJGb3JlaWduIExMUCIsInN0cyI6IlByb3Zpc2lvbmFsIiwiY3RqQ2QiOiJBUDAwNCIsImN0aiI6IkJDUCBUSFVNTUFLVU5UQSIsInRyYWRlTmFtIjoiQUxUT04gUExBU1RJQyBQUklWQVRFIExURCIsImFkYWRyIjpbeyJhZGRyIjp7ImJubSI6IkVMUEhJTlNUT05FIEJVSUxESU5HIiwic3QiOiIxMCwgVkVFUiBOQVJJTUFOIFJPQUQiLCJsb2MiOiJGT1JUIiwiYm5vIjoiMTAiLCJzdGNkIjoiUmFqYXN0aGFuIiwiZmxubyI6IjFTVCBGTE9PUiIsImx0IjoiNzQuMjE3OSIsImxnIjoiMjcuMDIzOCIsInBuY2QiOiI0MDAwMDEifSwibnRyIjpbIldob2xlc2FsZSBCdXNpbmVzcyJdfV0sInByYWRyIjp7ImFkZHIiOnsiYm5tIjoiS0FUR0FSQSBIT1VTRSIsInN0IjoiMTUsIEwgSkFHTU9IQU5EQVMgTUFSRyIsImxvYyI6Ik1BTEFCQVIgSElMTCIsImJubyI6IjUiLCJzdGNkIjoiTWFoYXJhc2h0cmEiLCJmbG5vIjoiNFRIIEZMT09SIiwibHQiOiI3NC4yMTc5IiwibGciOiIyNy4wMjM4IiwicG5jZCI6IjQwMDAwNiJ9LCJudHIiOlsiV2hvbGVzYWxlIEJ1c2luZXNzIl19fQ=="
                   }
               ]
           },
           "collaterals": [
               {
                   "collateralPrimaryId": "<GSTIN>_<INVOICENUM>",
                   "collateralPrimaryIdType": "GST_INVOICE",
                   "type": "GST_INVOICE",
                   "additionalIdentifiers": [],
                   "valuation": {
                       "value": "",
                       "currency": "",
                       "date": "",
                       "source": "GSTN"
                   },
                   "parties": [],
                   "documents": [
                       {
                           "format": "JSON",
                           "reference": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
                           "source": "GSTN",
                           "sourceIdentifier": "GSTN",
                           "type": "GSTN_B2B_INVOICE",
                           "isDataInline": true,
                           "data": "eyJjdGluIjoiMDFBQUJDRTIyMDdSMVo1IiwiY2ZzIjoiWSIsImludiI6W3siY2hrc3VtIjoiQkJVSUJVSVVJSktLQkpLR1VZRlRGR1VZIiwidXBkYnkiOiJTIiwiaW51bSI6IlMwMDg0MDAiLCJpZHQiOiIyNC0xMS0yMDE2IiwidmFsIjo3MjkyNDguMTYsInBvcyI6IjA2IiwicmNocmciOiJOIiwiZXRpbiI6IjAxQUFCQ0U1NTA3UjFaNCIsImludl90eXAiOiJSIiwiY2ZsYWciOiJOIiwiZGlmZl9wZXJjZW50IjowLjY1LCJvcGQiOiIyMDE2LTEyIiwiaXRtcyI6W3sibnVtIjoxLCJpdG1fZGV0Ijp7InJ0Ijo1LCJ0eHZhbCI6MTAwMDAsImlhbXQiOjMyNSwiY2FtdCI6MCwic2FtdCI6MCwiY3NhbXQiOjEwfX1dfV19"
                       }
                   ]
               }
           ],
           "guarantors": [],
           "applicants": [{
               "primaryId": "9898989898",
               "primaryIdType": "MOBILE"
           }],
           "terms" : {
               "requestedAmount" : "50000.00",
               "currency" : "INR"
           }
       }   
  ]
}

Sample Response Json

{
   "ack": {
     "error": "0",
     "traceId": "c8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
     "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

2) Create Loan Applications Response

This is the response for Create Loan Applications but invoked by the lender. No offers are rolled out as part of this API. If the lender system finds preliminary information sufficient for doing the loan processing, it will send “PROCESSING” as the status. Otherwise, it can reject the application citing a reason for the same

HTTP Verb - POST
API Endpoint - /v3/loanApplication/createLoanApplicationsResponse

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanApplictions

Array
LoanApplication

Yes

Array of Loan Applications

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp":"2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplications" : [{
       "loanApplicationId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "lender": {
           "primaryId": "AWW PA7645M",
           "primaryIdType": "PAN",
           "additionalIdentifiers": [],
           "name": "ABC Bank",
           "category": "ORGANIZATION",
           "contactDetails": [],
           "documents": []
       },
       "loanApplicationStatus" : "PROCESSING"
   }]
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "d8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

Consent APIs

1) Consent Handle Request

HTTP Verb - POST
API Endpoint - /v3/consent/consentHandleRequest

This API is used to request the lenders to send a consent request for fetching the bank account statements, GST historical data. The lender (FIU) checks with the AA and creates a consent handle internally once this API is triggered

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API response

loanApplicationIds

Array Alphanumeric

Ids are of length 35 each

Yes

UUID for the loan applications. Generated by LSP. These are the list of loan Applications for which borrower wants consents to be created

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

consent

Consent

Yes

This includes the consent details needed for the loan

Response payload

Key

type

validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "loanApplicationIds": [
       "f8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   ],
   "requestId": "g8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "consent": {
       "consentFetchType": "ONETIME",
       "vua": "[email protected]",
       "isAggregationEnabled": true,
       "consentAggregationId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acd",
       "lspInfo": {
           "lspId": "<AA can identify the LSP based on this>",
           "version": "<version of LSP>",
           "appName": "<Package name of the app>"
       }
   }
}

Sample Response Json

{
  "ack": {
    "error": "0",
    "traceId": "h8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
    "timestamp": "2018-12-06T11:39:57.153Z"
  }
}

2) Consent Handle Response

HTTP Verb - POST
API Endpoint - /v3/consent/consentHandleResponse

This API is invoked by the lenders to send the consent handles created in the AA system as part of the Consent Handle Request API triggered by the LSP.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API response

response

Response

Yes

Status of response. Whether success or has encountered error

consent

Consent

Yes

Consent details shared back by the lender

requestId

String

Length : 35

Yes

UUID used to tie request and response and for idempotency

Response payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Payload

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "h8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "i8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "consent": {
       "consentHandle": "j8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   }
}

Sample Response Payload

{
   "ack": {
     "error": "0",
     "traceId": "k8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
     "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

3) Consent Status Request

HTTP Verb - POST
API Endpoint - /v3/consent/consentStatusRequest

This API is invoked by the LSP to check the status of Consents.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API response

requestId

Alphanumeric

Ids are of length 35 each

Yes

UUID used to tie request and response and for idempotency

consent

Consent

Yes

Consent details

Response payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "l8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "requestId": "m8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "consent": {
       "consentHandle": "m8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   }
}

Sample Response Json

{
   "ack": {
     "error": "0",
     "traceId": "n8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
     "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

4) Consent Status Response

HTTP Verb - POST
API Endpoint - /v3/consent/consentStatusResponse

This API is invoked by the lender as a response informing the LSP regarding the status of the consents.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API response

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

consent

Consent

Yes

The consent details including the status of the consent

Response payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "o8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "p8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "consent": {
       "consentHandle": "q8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "consentStatus": "READY"
   }
}

Sample Response Json

{
   "ack": {
     "error": "0",
     "traceId": "r8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
     "timestamp": "2018-12-06T11:39:57.153Z"
   }
 }

Offers APIs

1) Generate Offers Request

HTTP Verb - POST
API Endpoint - /v3/offer/generateOffersRequest

Once the consents needed for fetching data are ready, the LSP sends a request to the Lenders to generate the offer for a set of loan applications. All these loan applications belong to the same borrower. This API is the trigger point for the lenders to use the consentIds that were created for the loanapplicationids as part of the Consent APIs to fetch the data from various FIPs as needed for the loan use case. Once the data from these sources have been obtained, the lender system runs its business rules on the data and creates the offers

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API response

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanApplicationIds

Array Alphanumeric

Each loan applicationId of length 35

Yes

UUID for the loan applications. Generated by LSP. These are the list of loan Applications for which borrower wants offers

Response payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
     "version": "1.0",
     "timestamp": "2018-12-06T11:39:57.153Z",
     "traceId": "s8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
     "orgId" : "LSP123"
   },
   "requestId" : "t8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplicationIds" : [
      "t8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   ]
}

Sample Response Json

{
   "ack": {
     "error": "0",
     "traceId": "v8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
     "timestamp": "2018-12-06T11:39:57.153Z"
   }
 }

2) Generate Offers Response

HTTP Verb - POST
API Endpoint - /v3/offer/generateOffersResponse

This API is invoked by the lender informing the borrower regarding the various loan offers that have been generated corresponding to each of the loan applications. This is a bulk API, where multiple loan offers can be sent to the borrower in one shot.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Status of response. Whether success or has encountered error

loanApplications

Array LoanApplication

Yes

Array of loan applications and corresponding offers

LoanApplication (Following shows fields of Loan Application that matter in this API)

Key

type

Validations

Mandatory

Description

loanApplicationId

Alphanumeric

Length : 35

Yes

Loan application id generated by the LSP to track the loan application

rejectionDetails

Array RejectionDetail

No

Reason given by the lender for rejecting a loan request raised by the borrower

actionRequired

Array ActionRequired

No

Details of the action requested from the borrower by the lender

offers

Array Offer

No

Details of the loan offer provided by the lender to the borrower

loanApplicationStatus

PROCESSING | OFFERED | OFFER_ACCEPTED | GRANTED | REJECTED| ACTION_REQUIRED

ENUM

Yes

Status indicating whether the lender has rolled out an offer

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "w8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "x8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplications": [
       {
           "loanApplicationId": "x8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "offers": [
               {
                   "id": "y8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
                   "description": "A short description of the offer",
                   "validTill": "2018-12-06T00:00:00.000Z",
                   "terms": {
                       "requestedAmount": "50000.00",
                       "currency": "INR",
                       "sanctionedAmount": "50000.00",
                       "interestType": "FIXED",
                       "interestRate": "12.00",
                       "interestAmount": "6000.00",
                       "totalAmount": "56000.00",
                       "tenure": {
                           "duration": "3",
                           "unit": "MONTH"
                       },
                       "legalAgreement": {
                           "type": "TEXT",
                           "data": "<Base64 Encoded Data>"
                       },
                       "charges": {
                           "prepayment": {
                               "chargeType": "RATE_BASED",
                               "description": "Description of charge calculation",
                               "data": {
                                   "rate": "6",
                                   "applicableParameter": "TOTAL_LOAN_AMOUNT"
                               }
                           },
                           "bounce": {
                               "chargeType": "FIXED_AMOUNT",
                               "description": "Description of charge calculation",
                               "data": {
                                   "amount": "3000.00"
                               }
                           },
                           "latePayment": {
                               "chargeType": "FIXED_AMOUNT",
                               "description": "Description of charge calculation",
                               "data": {
                                   "amount": "3000.00"
                               }
                           },
                           "processing": {
                               "chargeType": "FIXED_AMOUNT",
                               "description": "Description of charge calculation",
                               "data": {
                                   "amount": "3000.00"
                               }
                           }
                       }
                   },
                   "disbursement": {
                       "plans": [
                           {
                               "id": "hb8c6822bd4bbb4eb1b9e1b4996fbff8acb",
                               "automatic": false,
                               "scheduleType": "ONE_TIME",
                               "noOfInstallments": "1",
                               "totalAmount": "10000.00",
                               "status": "INACTIVE"
                           }
                       ],
                       "accountDetails": [
                           {
                               "id": "hb8c6822bd4bbb4eb1b9e1b4996fbff8acb",
                               "accountDataType": "ACCOUNT",
                               "data": {
                                   "accountType": "CURRENT",
                                   "maskedAccountNumber": "XXXXXXXXX9090"
                               }
                           }
                       ]
                   },
                   "repayment": {
                       "plans": [
                           {
                               "id": "a8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
                               "automatic": false,
                               "scheduleType": "ONE_TIME",
                               "payNowAllowed": false,
                               "changeMethodAllowed": false,
                               "noOfInstallments": "1",
                        "tenure" : {
                        "duration": "1",
                        "unit": "MONTH" 
                    }   , 
                               "title": "Title of the repayment plan",
                               "shortDescription": "short description of repayment plan",
                               "url": "lender url showing repayment details", 
                               "penalty": "0.00",
                               "principal": "9000.00",
                               "interestAmount": "1000.00",
                               "totalAmount": "10000.00",
                               "status": "INACTIVE"
                           }
                       ]
                   }
               }
           ],
           "loanApplicationStatus": "OFFERED"
       }
   ]
}

Sample Response Json

{
  "ack": {
    "error": "0",
    "traceId": "b8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
    "timestamp": "2018-12-06T11:39:57.153Z"
  }
}

3) Set Offer Request

HTTP Verb - POST
API Endpoint - /v3/offer/setOfferRequest

This API is invoked by the LSP to inform the lender about the offer that the borrower has chosen for a particular loan application.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API response

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

offer

Offer

Yes

UUID for the offer generated by the lender.

loanApplicationId

Alphanumeric

Length : 35

Yes

UUID for loanApplication. Generated by LSP

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "0.1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "c8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "requestId": "12c1ds6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplicationId": "d8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "offer": {
       "id": "y8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   }
}

Sample Response Json

{
 "ack": {
   "error": "0",
   "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "timestamp": "2018-12-06T11:39:57.153Z"
 }
}

4) Set Offer Response

HTTP Verb - POST
API Endpoint - /v3/offer/setOfferResponse

This API is invoked by the lender and is the asynchronous response to Accept Offer Request API.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanApplicationId

Alphanumeric

Length : 35

Yes

UUID for the loanApplication

loanApplicationStatus

PROCESSING | OFFERED | OFFER_ACCEPTED | GRANTED | REJECTED| ACTION_REQUIRED

Yes

Status of loan application

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "w8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "w8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplicationId": "w8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplicationStatus": "OFFER_ACCEPTED"
}

Sample Response Json

{
  "ack": {
    "error": "0",
    "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
    "timestamp": "2018-12-06T11:39:57.153Z"
  }
}

Loan Acceptance APIs

SMS Format for the OTP

[#] {6Digit OTP} is the One Time Password (OTP) to complete the loan process with {Lender Name}. {appToken}

Eg- # 467866 is the One Time Password (OTP) to complete the loan process with Lender ABC. 0aBCD7DMr7s

1) Trigger Loan Acceptance Request

HTTP Verb - POST
API Endpoint - /v3/loan/triggerLoanAcceptanceRequest

This API is invoked by the LSP when the user agrees to the terms of the agreement. The Asynchronous response for this API should include the lender sending an OTP to the phone number associated with the disbursement account.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanApplicationIds

Array Alphanumeric

Ids are of length 35 each

Yes

List of loan applications for which borrower has agreed to and wants to accept terms

credBlock

CredBlock

Yes

Credentials block which contains details for triggering and accepting loan

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanApplicationIds": [
       "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   ],
   "credBlock": {
       "type": "OTP",
       "data": {
           "appToken": "0aBCD7DMr7s"
       }
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

2) Trigger Loan Acceptance Response

HTTP Verb - POST
API Endpoint - /v3/loan/triggerLoanAcceptanceResponse

This API is invoked by the Lender when the Lender sends out an OTP to the phone number associated with the disbursement account. This API is an asynchronous response to the OTP trigger request by the LSP.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

credBlock

CredBlock

Yes

Credentials block which contains details for triggering and accepting loan

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "credBlock": {
       "type": "OTP",
       "data": {
           "otpSessionKey": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "maskedPhoneNumber": "xxxxxx9090"
       }
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

3) Verify Loan Acceptance Request

HTTP Verb - POST
API Endpoint - /v3/loan/verifyLoanAcceptanceRequest

This API is invoked by the LSP when the user enters the OTP received on the mobile number associated with the disbursement account and agrees to the terms of the agreement. The asynchronous response for this API should include the lender acknowledging the receipt of OTP and verifying if the user has entered the correct OTP that was shared by the lender.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

credBlock

CredBlock

Yes

Credentials block which contains details for triggering and accepting loan

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "requestId": "es1c6822bd4bbb4eb1b9e1b4996fbff8acb",
   "credBlock": {
       "type": "OTP",
       "data": {
           "otpSessionKey": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "otp": "689451"
       }
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

4) Verify Loan Acceptance Response

HTTP Verb - POST
API Endpoint - /v3/loan/verifyLoanAcceptanceResponse

This API is invoked by the Lender when the OTP entered by the user is shared through the LSP. This API acknowledges the receipt of OTP and verifies if the user has entered the correct OTP that was shared by the lender on the mobile number associated with the disbursement account.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Status of response. Whether success or has encountered error

credBlock

CredBlock

Yes

Credentials block which contains details for triggering and accepting loan

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acc",
   "credBlock": {
       "type": "OTP",
       "data": {
           "otpSessionKey": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "status": "SUCCESS"
       }
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

Grant Loan APIs

1) Grant Loan Request

HTTP Verb - POST
API Endpoint - /v3/loan/grantLoanRequest

This API is invoked by the LSP once the borrower has agreed to the terms of the agreement, given consent for monitoring and set up a repayment option. This API creates the actual loan in the lender’s system.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length :35

Yes

UUID used to tie request and response and for idempotency

loanApplicationId

Alphanumeric

Length :35

Yes

UUID for the loan application. Generated by LSP

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

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

Sample Response JSON

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

2) Grant Loan Response

This method is called be the Lender when the Grant Loan processing is completed. This informs the borrower about the status of the loan in the lender system. Upon successful creation of a loan in the system, the lender returns all the details of the loan.

HTTP Verb - POST
API Endpoint - /v3/loan/grantLoanResponse

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

Unique identifier for loan.Generated by Lender.Will be generated if loanStatus =GRANTED.

loanStatus

GRANTED | REJECTED| DEFAULTED | COMPLETED | ACTION_REQUIRED

ENUM

Yes

Status of the loan

terms

LoanTerms

Yes

Detailed terms of the loan.

repayment

ChosenRepayment

Yes

Repayment details for the loan

disbursement

ChosenDisbursement

Yes

Disbursement details of the loan

rejectionDetails

Array RejectionDetail

No

To be filled if the status of the loan is REJECTED. This object will have the details of why the loan was rejected

actionRequired

Array ActionRequired

No

To be filled if the status of the loan is ACTION_REQUIRED. This object captures the details of any action that the lender wants the borrower to do

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "terms": {
       "requestedAmount": "50000.00",
       "currency": "INR",
       "sanctionedAmount": "50000.00",
       "interestType": "FIXED",
       "interestRate": "12",
       "interestAmount": "6000.00",
       "totalAmount": "56000.00",
       "tenure": {
           "duration": "3",
           "unit": "MONTH"
       },
       "legalAgreement": {
           "type": "TEXT",
           "data": "<Base64 Encoded Data>"
       },
       "charges": {
           "prepayment": {
               "chargeType": "RATE_BASED",
               "description": "Description of charge calculation",
               "data": {
                   "rate": "6",
                   "applicableParameter": "TOTAL_LOAN_AMOUNT"
               }
           },
           "bounce": {
               "chargeType": "FIXED_AMOUNT",
               "description": "Description of charge calculation",
               "data": {
                   "amount": "3000.00"
               }
           },
           "latePayment": {
               "chargeType": "FIXED_AMOUNT",
               "description": "Description of charge calculation",
               "data": {
                   "amount": "3000.00"
               }
           },
           "processing": {
               "chargeType": "FIXED_AMOUNT",
               "description": "Description of charge calculation",
               "data": {
                   "amount": "3000.00"
               }
           }
       }
   },
   "disbursement": {
       "plan": {
           "id": "hb8c6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "noOfInstallments": "1",
           "totalAmount": "10000.00",
           "status": "ACTIVE"
       },
       "accountDetails": {
           "accountDataType": "ACCOUNT",
           "data": {
               "accountType": "CURRENT",
               "maskedAccountNumber": "XXXXXXXXX9090"
           }
       }
   },
   "repayment": {
       "plan": {
           "id": "a8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "payNowAllowed": false,
           "changeMethodAllowed": false,
           "noOfInstallments": "1",
           "principal": "9000.00",
           "interestAmount": "1000.00",
           "penalty": "0.00",
           "totalAmount": "10000.00",
           "status": "ACTIVE"
       }
   },
   "loanStatus": "GRANTED"
}

Sample Response json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

3) Loan Summary Request

HTTP Verb - POST
API Endpoint - /v3/loan/loanSummaryRequest

This API is invoked by the LSP to get the summary of the loan as of the current date.

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

Id of loan whose status is being enquired. Generated by lender

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

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

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

4) Loan Summary Response

This method is called be the Lender as a response to Loan Summary Request.

HTTP Verb - POST
API Endpoint - /v3/loan/loanSummaryResponse

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

Unique identifier for loan generated by Lender

loanStatus

GRANTED | DEFAULTED | COMPLETED | OVERDUE

ENUM

Yes

Status of the loan

createdDate

Date

Yes

Date when loan was created

startDate

Date

Yes

Date from when loan is active

endDate

Date

Yes

End date till when loan is active

summary

Summary

Yes

Summary details of the loan

Summary

Key

type

Validations

Mandatory

Description

nextRepayment

Payment

Yes

Details of the next scheduled repayment

currentRepayment

Payment

Yes

Details of the current repayment. This includes the repayment details as of current date.

principalPaid

String

Max Length : 20

Yes

Principal paid in the past. Upto 2 digits precision

interestPaid

String

Max Length : 20

Yes

Interest Paid. Upto 2 digits precision

penaltyPaid

String

Max Length : 20

Yes

Penalty Paid. Upto 2 digits precision

principalPending

String

Max Length : 20

Yes

Principal Pending. Upto 2 digits precision

interestPending

String

Max Length : 20

Yes

Interest Pending. Upto 2 digits precision

amountDisbursed

String

Max Length : 20

Yes

Amount disbursed till date. Upto 2 digits precision

amountRepaid

String

Max Length : 20

Yes

Amount disbursed till date. Upto 2 digits precision

tenure

LoanTenure

Yes

Tenure of the loan

description

String

Max Length : 1000

Yes

Short description about the loan.

Response Payload

Key

type

Validation

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanStatus": "GRANTED",
   "createdDate": "2019-12-30T13:55:00Z",
   "startDate": "2019-12-30T00:00:00Z",
   "endDate": "2020-03-01T00:00:00Z",
   "summary": {
       "nextRepayment": {
           "totalAmount": "5000.00",
           "principal" : "4000.00",
           "interestAmount" : "1000.00",
           "penalty" : "0.00",
           "fee" : "0.00",
           "date": "2020-03-01T00:00:00Z",
           "installmentNumber": "1"
       },
       "currentRepayment": {
           "totalAmount": "5000.00",
           "principal" : "4000.00",
           "interestAmount" : "1000.00",
           "penalty" : "0.00",
           "fee" : "0.00",
           "date": "2020-10-10",
           "installmentNumber": "1"
       },
       "principalPaid": "10000.00",
       "interestPaid": "100.00",
       "penaltyPaid": "10.00",
       "principalPending": "10000.00",
       "interestPending": "100.00",
       "amountDisbursed": "1000.00",
       "amountRepaid": "1000.00",
       "tenure": {
      "duration": "3",
           "unit": "MONTH"
       },
       "description": "short description for the loan"
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

5) Get Loan Request

HTTP Verb - POST
API Endpoint - /v3/loan/getLoanRequest

This API is invoked by the LSP when the LSP wants to get the details of the loan.

Request Payload

Key

type

Validations

Mandatory

Duration

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

Unique identifier for the loan generated by Lender

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

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

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

6) Get Loan Response

This method is called by the Lender and it returns all the details of the loan.

HTTP Verb - POST
API Endpoint - /v3/loan/getLoanResponse

Request Payload

Key

type

Validation

Mandatory

Description

metadata

MetaData

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Status of response. Whether success or has encountered error

loanId

Alphanumeric

Length : 35

Yes

Unique identifier for loan generated by Lender

loanStatus

GRANTED | DEFAULTED | COMPLETED | OVERDUE

ENUM

Yes

Status of the loan

createdDate

Date

Yes

Date when loan was created

startDate

Date

Yes

Date from when loan is active

endDate

Date

Yes

Date till when loan is active

type

CASHFLOW | PERSONAL | HOME | VEHICLE | BUSINESS

ENUM

Yes

Type of Loan

borrower

Borrower

Yes

Borrower details shared by LSP during createLoanApplication

lender

Lender

Yes

Details about the lender

collateral

Array Collateral

Yes

Details of the collateral used for the loan. Shared by LSP during createLoanApplication

guarantors

Array Guarantor

Yes

List of guarantors.

terms

LoanTerms

Yes

Details of the terms of the loan

disbursement

ChosenDisbursement

Yes

Disbursement details of the loan

repayment

ChosenRepayment

Yes

Repayment details of the loan

applicants

Array Applicant

Yes

List of applicants

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanStatus": "GRANTED",
   "createdDate": "2019-12-30T13:55:00Z",
   "startDate": "2019-12-30T00:00:00Z",
   "endDate": "2020-03-01T00:00:00Z",
   "type": "CASHFLOW",
   "borrower": {
       "primaryId": "CPAA1234A",
       "primaryIdType": "PAN",
       "additionalIdentifiers": [],
       "name": "John doe",
       "category": "ORGANISATION",
       "contactDetails": [
           {
               "type": "PRIMARY",
               "phone": "7777777777",
               "email": "[email protected]",
               "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": []
   },
   "collaterals": [
       {
           "collateralPrimaryId": "<GSTIN>_<INVOICENUM>",
           "collateralPrimaryIdType": "GST_INVOICE",
           "type": "GST_INVOICE",
           "additionalIdentifiers": [],
           "valuation": {
               "value": "",
               "currency": "",
               "date": "",
               "source": "GSTN"
           },
           "parties": [],
           "documents": []
       }
   ],
   "guarantors": [],
   "applicants": [
       {
           "primaryId": "9898989898",
           "primaryIdType": "MOBILE"
       }
   ],
   "terms": {
       "requestedAmount": "50000.00",
       "currency": "INR",
       "sanctionedAmount": "50000.00",
       "interestType": "FIXED",
       "interestRate": "12.00",
       "interestAmount": "6000.00",
       "totalAmount": "56000.00",
       "tenure": {
           "duration": "3",
           "unit": "MONTH"
       },
       "legalAgreement": {
           "type": "TEXT",
           "data": "<Base64 Encoded Data>"
       },
       "charges": {
           "prepayment": {
               "chargeType": "RATE_BASED",
               "description": "Description of charge calculation",
               "data": {
                   "rate": "6",
                   "applicableParameter": "TOTAL_LOAN_AMOUNT"
               }
           },
           "bounce": {
               "chargeType": "FIXED_AMOUNT",
               "description": "Description of charge calculation",
               "data": {
                   "amount": "3000.00"
               }
           },
           "latePayment": {
               "chargeType": "FIXED_AMOUNT",
               "description": "Description of charge calculation",
               "data": {
                   "amount": "3000.00"
               }
           },
           "processing": {
               "chargeType": "FIXED_AMOUNT",
               "description": "Description of charge calculation",
               "data": {
                   "amount": "3000.00"
               }
           }
       }
   },
   "disbursement": {
       "plan": {
           "id": "hb8c6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "noOfInstallments": "1",
           "totalAmount": "10000.00",
           "status": "ACTIVE"
       },
       "accountDetails": {
           "accountDataType": "ACCOUNT",
           "data": {
               "accountType": "CURRENT",
               "maskedAccountNumber": "XXXXXXXXX9090"
           }
       }
   },
   "repayment": {
       "plan": {
           "id": "a8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "payNowAllowed": false,
           "changeMethodAllowed": false,
           "noOfInstallments": "1",
           "principal": "9000.00",
           "interestAmount": "1000.00",
           "penalty": "0.00",
           "totalAmount": "10000.00",
           "status": "ACTIVE"
       },
       "method": {
           "type": "EMANDATE_UPI",
           "status": "ACTIVE",
           "data": {
               "refNumber": "Ref1234",
               "amount": "50000.00",
               "amountType": "MAX",
               "activeFrom": "10-03-2020",
               "expiryDate": "10-09-2020",
               "destinationAccount": {
                   "accountDataType": "ACCOUNT",
                   "data": {
                       "accountType": "CURRENT",
                       "maskedAccountNumber": "XXXXXXXX9090",
                   }
               },
               "sourceAccount": {
                   "accountDataType": "ACCOUNT",
                   "data": {
                       "accountType": "CURRENT",
                       "maskedAccountNumber": "XXXXXXXX9090"
                   }
               }
           }
       }
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

7) Loan Statement Request

This method is called be the LSP to get the account statement for the loan for a specified period. If the start and end dates are blank, it will return the entire Loan Statement

HTTP Verb - POST
API Endpoint - /v3/loan/loanStatementRequest

Request Payload

Key

type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

Unique identifier for loan generated by Lender

startDate

Date

No

Start date from which statement is requested

endDate

Date

No

End date till which the statement is requested

Response Payload

Key

type

Validation

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId" : "LSP123"
   },
   "requestId": "e8cc6822-d4bb-4eb1-9e1b-4996fbff8acb",
   "loanId": "e8cc6822-d4bb-4eb1-9e1b-4996fbff8acb"
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

8) Loan Statement Response

This method is called be the Lender to return the loan account statement back to the LSP

HTTP Verb - POST
API Endpoint - /v3/loan/loanStatementResponse

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Status of response. Whether success or has encountered error

loanId

Alphanumeric

Length : 35

Yes

Unique identifier for loan generated by Lender

accountStatement

Array Transaction

Yes

Details of each transaction carried out on the Loan Account

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Payload

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "accountStatement": [
       {
           "date": "2020-03-01T00:00:00Z",
           "narration": "Repayment of Loan no : xxxxxxx9090",
           "txnRefNo": "004618602124",
           "amount": "50000.00",
           "type": "DEPOSIT",
           "closingBalance": "50000.00"
       }
   ]
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

9) List Loans Request

This method is called by the LSP to return the list of loans provisioned for a borrower.

HTTP Verb - POST
API Endpoint - /v3/loan/listLoansRequest

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

borrower

Borrower

Yes

Borrower details for the loan

collateral

Collateral

No

Collateral used

startDate

Date

No

Start date from when the list of loans should be fetched

endDate

Date

No

End date till which list of loans should be fetched

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Payload

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "borrower": {
       "primaryId": "CPAA1234A",
       "primaryIdType": "PAN"
   }
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

10) List Loans Response

This method is called by the Lender to return the list of loans provisioned for a borrower.

HTTP Verb - POST
API Endpoint - /v3/loan/listLoansResponse

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Status of response. Whether success or has encountered error

loans

Array LoanDetail

Yes

Details of the loans granted for the borrower

Response Payload

Key

Types

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Payload

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
    "response": {
       "error": "0"
   },
   "loans": [
       {
           "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "terms": {
               "requestedAmount": "50000.00",
               "currency": "INR",
               "sanctionedAmount": "50000.00",
               "interestType": "FIXED",
               "interestRate": "12.00",
               "interestAmount": "6000.00",
               "totalAmount": "56000.00",
               "tenure": {
                   "duration": "3",
                   "unit": "MONTH"
               },
               "legalAgreement": {
                   "type": "TEXT",
                   "data": "<Base64 Encoded Data>"
               },
               "charges": {
                   "prepayment": {
                       "chargeType": "RATE_BASED",
                       "description": "Description of charge calculation",
                       "data": {
                           "rate": "6",
                           "applicableParameter": "TOTAL_LOAN_AMOUNT"
                       }
                   },
                   "bounce": {
                       "chargeType": "FIXED_AMOUNT",
                       "description": "Description of charge calculation",
                       "data": {
                           "amount": "3000.00"
                       }
                   },
                   "latePayment": {
                       "chargeType": "FIXED_AMOUNT",
                       "description": "Description of charge calculation",
                       "data": {
                           "amount": "3000.00"
                       }
                   },
                   "processing": {
                       "chargeType": "FIXED_AMOUNT",
                       "description": "Description of charge calculation",
                       "data": {
                           "amount": "3000.00"
                       }
                   }
               }
           }
       }
   ]
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

Repayment APIs

The Repayment APIs between LSP and Lenders have been standardized. The basic expectations from the APIs are the below

  1. When the lender returns an offer, a list of repayment plans should be provided which include the details about the schedule/when the repayments can be made.
  2. The Borrower chooses a repayment plan upon which setRepaymentPlanRequest is called. The lender returns a payment page url as part of the response to setRepaymentPlan. This url will be loaded by the LSP inside the app which would show the kinds of payment methods that the lender supports for the chosen repayment plan.
  3. The Borrower can choose a method on the payment page provided by the lender. In case of BHIM for lending, this will be a one-time e-mandate which the borrower can initiate by entering his vpa details. Post this, the lender will trigger a request to the PSP associated with the vpa for getting the authorization from the borrower. Post successful authorization, e-mandate becomes active and the repayment plan is also considered to be ACTIVE.
  4. When the repayment is to be initiated, by an option other than e-mandate(not for BHIM for Lending), the user will be taken to the payment page from where he can choose a payment method and make the payment.

1) Get Repayment Plans Request

HTTP Verb - POST
API Endpoint - /v3/repayment/getRepaymentPlansRequest

This API is used to get the list of repayment plans provided by the lender for a particular loan.

Request payload

key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

loanId

Alphanumeric

Length : 35

Yes

UUID for Loan. Generated by Lender

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

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

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

2) Get Repayment Plans Response

HTTP Verb - POST
API Endpoint - /v3/repayment/getRepaymentPlansResponse

This API is invoked by the lender to the LSP returning the list of Repayment plans available for a particular loan.

Request payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Response indicating whether error occurred

plans

Array PaymentPlan

Yes

Repayment Plans for the loan

Response Payload

Key

type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "plans": [
       {
           "id": "a8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "payNowAllowed": false,
           "changeMethodAllowed": false,
           "noOfInstallments": "1",
           "totalAmount": "10000.00",
           "title": "Title of the repayment plan",
           "shortDescription": "short description of repayment plan",
           "url": "lender url showing repayment details"
       },
       {
           "id": "hb8c6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "payNowAllowed": false,
           "changeMethodAllowed": false,
           "noOfInstallments": "1",
           "totalAmount": "10000.00",          
           "title": "Title of the repayment plan",
           "shortDescription": "short description of repayment plan",
           "url": "lender url showing repayment details"
       }
   ]
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

3) Set Repayment Plan Request

HTTP Verb - POST
API Endpoint - /v3/repayment/setRepaymentPlanRequest

This API is invoked by the LSP to inform the lender system about the details of the repayment plan that will be used by the borrower. The LSP will need to send either the LoanId or the LoanApplicationId as the case might be.

Request Payload

Key

Type

Validation

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

loanApplicationId

Alphanumeric

Length : 35

No

UUID for the loan application. Generated by LSP. This has to be there only if the request is made before grant loan is called.

loanId

Alphanumeric

Length : 35

No

UUID for the loan. Generated by Lender. This will only be there if the repayment is created after the Grant Loan api call.

requestId

Alphanumeric

Length : 35

yes

UUID used to tie request and response and for idempotency

plan

PaymentPlan

yes

Repayment plan chosen by the borrower for the loan

Response payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "loanApplicationId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "plan": {
      "id": "z8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   }
}

Sample Response Json

{
   "ack": {
      "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

4) Set Repayment Plan Response


HTTP Verb - POST
API Endpoint - /v3/repayment/setRepaymentPlanResponse

This API is invoked by the lender to the LSP giving the payment url where he can enter details of repayment.

Request payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Response indicating whether error occurred

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

plan

PaymentPlan

Yes

Details of the chosen repayment plan

Response Payload

Key

Type

Validation

Mandatory

Description

ack

Ack

yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "plan": {
           "id": "z8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
        "paymentUrl": "https://abcbank.in/z8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
           "status": "PENDING_AUTH",
           "automatic": false,
           "payNowAllowed" : false,
           "changeMethodAllowed" : false,
           "scheduleType": "ONE_TIME",
           "noOfInstallments" : "1",
           "totalAmount": "10000.00"
       }
   }
}

Sample Response Json

{
   "ack": {
  "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

5) Set Repayment Plan Status Request

HTTP Verb - POST
API Endpoint - /v3/repayment/setRepaymentPlanStatusRequest

This API is used by LSP to check the status of a previously initiated set repayment plan request. This API is called once the payment page of the lender is loaded and the borrower choses a repayment method associated with the chosen repayment plan.

Request payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

plan

PaymentPlan

Yes

Payment plan chosen

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   }
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8aca",
   "plan": {
      "id": "z8cc6822bd4bbb4eb1b9e1b4996fbff8acb"
   }
}
{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

6) Set Repayment Plan Status Response / Webhook

HTTP Verb - POST
API Endpoint - /v3/repayment/setRepaymentPlanStatusResponse

This API is used by lenders to inform LSP about the status of a previously initiated set Repayment.The API returns the status of the repayment plan that the borrower has chosen. In case, the borrower has chosen e-mandate as the repayment method in payment page url, the status of the repayment plan becomes ACTIVE only after successful authorization of the e-mandate on the PSP by the borrower.

Request payload

Key

Type

Validations

Mandatory

Description

meatdata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Response indicating whether error occurred

requestId

Alphanumeric

Length : 35

No

UUID used to tie request and response and for idempotency

plan

PaymentPlan

Yes

Plan for the loan.

loanId

Alphanumeric

Length : 35

No

UUID for loan. Generated by Lender

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "plan": {
           "id": "a8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
           "automatic": false,
           "scheduleType": "ONE_TIME",
           "payNowAllowed" : false,
           "changeMethodAllowed" : false,
           "noOfInstallments" : "1",
           "totalmount": "10000.00",
           "status": "ACTIVE"
   }
}

Sample Response Json

{
   "ack": {
    "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

7) Trigger Repayment Request

HTTP Verb - POST
API Endpoint - /v3/repayment/triggerRepaymentRequest

This API is invoked by the LSP to inform the lender to trigger a repayment.

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

UUID for the loan. Generated by Lender.

payment

Payment

Yes

Payment details

Response payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "payment": {
       "id": "hhcc6822bd4bbb4eb1b9e1b4996fbff8acb",
   }
}

Sample Response Json

{
   "ack": {
      "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

8) Trigger Repayment Response


HTTP Verb - POST
API Endpoint - /v3/repayment/triggerRepaymentResponse

This API is invoked by the lender to the LSP giving the lender payment page url from where the borrower can make the payment. Lender also generates an id for the payment which becomes the reference for LSP to check the status of repayment.

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Response indicating whether error occurred

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

payment

Payment

Yes

Details of the Repayment

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "response": {
       "error": "0"
   },
   "payment": {
       "id": "hhcc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "status": "PENDING_AUTH",
       "paymentUrl": "https://abcbank.in/hhcc6822bd4bbb4eb1b9e1b4996fbff8acb"
   }
}

Sample Response Json

{
   "ack": {
  "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

9) Trigger Repayment Status Request

HTTP Verb - POST
API Endpoint - /v3/repayment/triggerRepaymentStatusRequest

This API is used by LSP to check the status of a previously initiated repayment transaction.

Request payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

loanId

Alphanumeric

Length : 35

Yes

UUID for the loan. Generated by Lender.

payment

Payment

Yes

Payment details generated by the lender during the TriggerRepaymentStatusResponse API. PaymentId is used to check the status of the specific payment transaction

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8adf",
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8adf",
   "payment": {
    "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8adf",
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

10) Trigger Repayment Status Response

HTTP Verb - POST
API Endpoint - /v3/repayment/triggerRepaymentStatusResponse

This API is used by lenders to inform LSP about the status of a previously initiated repayment.

Request payload

Key

Type

Validation

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Response indicating whether error occurred

payment

Payment

Yes

Payment details of a previously initiated payment

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json :

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "response": {
       "error": "0"
   },
   "payment": {
       "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8adf",
       "paymentMethodType": "UPI",
       "totalAmount": "5000.00",
       "date": "2018-12-06T11:39:57.153Z",
       "status": "SUCCESS",
       "installmentNumber": "1",
       "txnRefNo": "004618602124"
   }
}

Sample Response Json

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

11) Confirm Repayment

HTTP Verb - POST
API Endpoint - /v3/repayment/confirmRepayment

This API is used by lenders to inform LSP about the status of a repayment handled directly by the lender (Triggered on Lender side - Payment on the branch or auto E-Mandate repayment).

Request payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

response

Response

Yes

Response indicating whether error occurred

payment

Payment

Yes

Payment details of a previously initiated payment

loanId

Alphanumeric

Alphanumeric

Yes

Unique Id for the loan.

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request Json :

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "response": {
       "error": "0"
   },
   "payment": {
       "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8adf",
       "paymentMethodType": "EMANDATE_UPI",
       "totalAmount": "5000.00",
       "date": "2018-12-06T11:39:57.153Z",
       "status": "SUCCESS",
       "installmentNumber": "1",
       "txnRefNo": "004618602124"
   }
}

Sample Response Json :

{
   "ack": {
       "error": "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

Disbursement APIs

Disbursement includes 2 main objects. A disbursement plan which specifies the specifics of when disbursement will be carried out and disbursement account which indicates where the loan disbursement will be carried out.

1) Trigger Disbursement Request

HTTP Verb - POST
API Endpoint - /v3/disbursement/triggerDisbursementRequest

This API is to be used when the user wants the money to be disbursed immediately.

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

loanId

Alphanumeric

Length : 35

Yes

UUID for the loan. Generated by Lender

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

payment

Payment

Yes

Payment details

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

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

Sample Response Json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

2) Trigger Disbursement Response

HTTP Verb - POST
API Endpoint - /v3/disbursement/triggerDisbursementResponse

This API is invoked by the lender to inform the status of the disbursement request.

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

payment

Payment

Yes

Payment details

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId" : "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "payment": {
       "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
      "totalAmount": "5000.00",
       "date": "2018-12-06T11:39:57.153Z",
       "status": "PROCESSING",
       "installmentNumber": "1"
   }
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

3) Trigger Disbursement Status Response

HTTP Verb - POST
API Endpoint - /v3/disbursement/triggerDisbursementStatusResponse

This API is invoked by the lender to inform the status of the previously initiated trigger disbursement status request.

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

payment

Payment

Yes

Payment details

Response Payload

Key

Type

Validartions

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId" : "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "payment": {
       "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
      "totalAmount": "5000.00",
       "date": "2018-12-06T11:39:57.153Z",
       "status": "SUCCESS",
       "installmentNumber": "1",
       "txnRefNo": "004618602124"
   }
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

Loan Dispute Management APIs

1) Raise Dispute Request

HTTP Verb - POST
API Endpoint - /v3/loan/dispute/raiseDisputeRequest

This API is invoked by the LSP to create a dispute in the lender system for an issue that is faced by the borrower.

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

loanId

Alphanumeric

Length : 35

No

UUID for Loan. Generated by Lender

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

dispute

Dispute

Yes

Dispute details

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "loanId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "dispute": {
       "description" : "Amount not disbursed to the account yet"
   }
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

2) Raise Dispute Response

This method is invoked by the lender once the Raise Dispute processing is done.

HTTP Verb - POST
API Endpoint - /v3/loan/dispute/raiseDisputeResponse

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

requestId

Alphanumeric

Length : 35

Yes

UUID used for idempotency

dispute

Dispute

Yes

Dispute Details

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{ 
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "dispute": {
       "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "status": "NEED_MORE_INFO",
       "url": "URL where dispute progress can be tracked"
   }
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

3) Dispute Status Request

HTTP Verb - POST
API Endpoint - /v3/loan/dispute/disputeStatusRequest

This API is invoked by the LSP to check the status of the dispute.

Request Payload

Key

Type

Validationsd

Mandatory

Descriotion

metadata

Metadata

Yes

Metadata specific to each API request.

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

dispute

Dispute

Yes

Dispute Details

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

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

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

4) Dispute Status Response / Webhook

This API is invoked by the lender to inform the LSP regarding the status of the dispute.

HTTP Verb - POST
API Endpoint - /v3/loan/dispute/disputeStatusResponse

Request Payload

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

dispute

Dispute

Yes

Dispute Details

requestId

Alphanumeric

Length : 35

Yes

UUID used to tie request and response and for idempotency

Response Payload

Key

Type

Validations

Mandatory

Description

ack

Ack

Yes

Acknowledgement block indicating the receipt and status of request

Sample Request json

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "FIU123"
   },
   "response": {
       "error": "0"
   },
   "requestId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
   "dispute": {
       "id": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "status": "CLOSED"
   }
}

Sample Response json

{
   "ack": {
       "error" : "0",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "timestamp": "2018-12-06T11:39:57.153Z"
   }
}

Meta APIs

1) Heartbeat

This API is used by the LSP to check if the lender system is up and running

HTTP Verb - Get
API Endpoint - /v3/heartbeat

Request Parameters - None

Response Parameters

Key

Type

Validations

Mandatory

Description

metadata

Metadata

Yes

Metadata specific to each API request.

response

Response

Yes

Status of response. Whether success or has encountered error

status

UP | DOWN

ENUM

Indicates whether the Lender system is UP or Down

Sample Response

{
   "metadata": {
       "version": "1.0",
       "timestamp": "2018-12-06T11:39:57.153Z",
       "traceId": "e8cc6822bd4bbb4eb1b9e1b4996fbff8acb",
       "orgId": "LSP123"
   },
   "response": {
       "error": "0"
   },
   "status": "SUCCESS"
}

Did this page help you?