Aditya Birla Finance Limited: Lender API V2 Integration

API Latest Version Release Date: 07/06/2021

Document Revision History
Revision Revised By Summary of modifications
Date
02/03/2021 Neil Haria –
[[email protected]]
07/06/2021 Urvish Lodaria Added new status codes for the
API and callbacks expected after
[[email protected]] Softcell fixes
02/07/2021 Neil Haria Added `abfl_application_id` in
callback response
[[email protected]]

Document Review History

Review Date Reviewed By Reviewed Version
Table of Contents
API Reference 3
Authentication 3
Request and Response 4
Standard Response codes 8
API Reference

The API will be organized around REST. Our API will have predictable, resource-oriented
URLs, and will use HTTP response codes to indicate API errors. Secure interaction with the
API from a client-side web application or backend code will be supported. JSON will be
returned by all API responses, including errors.

Any web programming language should be able to make and receive HTTP networking calls.

Authentication

All API calls will be authenticated using an X-AUTH-TOKEN passed in the header of the
request call. X-AUTH-TOKEN value in the header will be validated for correctness before
invoking the API backend. The token can be created by the credentials shared to the partner
at the time of integration.
Request and Response
Method Name decisionEngine
HTTP Method POST
URL (environment = UAT) https://b2bpartner-api-uat.abfldirect.com/v2/
Headers X-AUTH-TOKEN

Sample Request Structure:

{
"source": "GROWW",
"accountId": "GROWW914258",
"productCode": "GROWW",
"customerReport": {
"kycInfo": {
"firstName": "RAJAN",
"middleName": "DEV",
"lastName": "TEST",
"mobile": "7385134103",
"email": "[email protected]",
"panNumber": "CBBAC2137E",
"gender": "F",
"dob": "1975-05-13",
"addressLine1": "56t",
"addressLine2": "Mumbai",
"addressLine3": "Maharashtra",
"city": "Mumbai",
"state": "Maharashtra",
"pincode": 400071
},
"loanApplicationRequest": {
"requestedLoanAmount": 50000.0,
"roi": "2.0",
"tenure": "12"
}
}
}
 Input:

The request should contain the following parameters.

Parameter Name Mandatory/Non- Valid Values/Formats Type of variable and

mandatory field condition on it
source Mandatory - Allowed chars = ascii_lowercase + e.g. GROWW
ascii_uppercase
- Min length – 3
- Max length - 50

accountId Mandatory - Allowed chars = ascii_lowercase + Loan Application ID

ascii_uppercase + digits + ['_', ‘-‘]
- Min length – 3
- Max length - 50

productCode Mandatory - Allowed chars = ascii_lowercase +

ascii_uppercase + digits + [‘_’] e.g. GROWW

firstName Mandatory - Allowed chars = ascii_lowercase +

ascii_uppercase First Name

middleName Optional - Allowed chars = ascii_lowercase + Middle Name

ascii_uppercase

lastName Mandatory - Allowed chars = ascii_lowercase + Last Name

ascii_uppercase

mobile Mandatory - Allowed chars = digits 9000329031

- Min length – 10
- Max length - 10
 email Mandatory - Alphanumeric string. Actual Email ID
- No special characters allowed
except
- `-`, `_`, `.`

panNumber Mandatory - Alphanumeric string. Actual PAN Number

- No special characters allowed
- Min length - 10
- Max length - 10

dob Mandatory - YYYY-MM-DD format Date of Birth

gender Mandatory - Allowed chars `M` (male)

- `M` (male) `F` (female)
- `F` (female) `O` (other)
- `O` (other)

requestedLoanAmount Mandatory - Numeric only Loan Amount

- Type (numeric)

addressLine1 Mandatory - Alphanumeric string. Address Line 1

- No special characters like,
‘,",--,//,!,#,*,(,),%,`,~ are
supported

addressLine2 Optional - Alphanumeric string. Address Line 2

- No special characters like,
‘,",--,//,!,#,*,(,),%,`,~ are
supported

addressLine3 Optional - Alphanumeric string. Address Line 3

- No special characters like,
‘,",--,//,!,#,*,(,),%,`,~ are
supported
 city Mandatory - Allowed chars = ascii_lowercase + City
ascii_uppercase

state Mandatory - Allowed chars = ascii_lowercase + State

ascii_uppercase
-

pincode Mandatory - Numeric only Pin Code

- Type (numeric)
- Min length - 6
- Max length - 6

roi Mandatory - Numeric only with decimal Rate of Interest

support
- Type (string)

tenure Mandatory - Numeric only Tenure

- Type (string)

Headers:

Header Name Description Valid Values/Formats

X-AUTH-TOKEN X-AUTH-TOKEN to be generated and sent Alphanumeric string.
as per the credentials shared by the No special characters like,
business or technology team ‘,",--,//,!,#,*,(,),%,`,~ are
supported

Output:

Output json body structure for all possible HTTPS responses codes have already been defined in the
STANDARD RESPONSE CODES sections. Response json body will have the following fields –

a. responseStatus – (string) - (SUCCESS, ERROR).

b. error - (dictionary) (contains code, description and errorType for all non-successful responses).

Sample Response Json:

{'responseStatus': 'SUCCESS'}
Standard Response codes
HTTPS Code Response Type Meaning Response Body
200 Success Request was successfully {'responseStatus': 'SUCCESS'}
processed. ERROR_MESSAGE will
be blank in this case.
412 InProgress Request for same account is either {
Request/BRE in progress or decision is already "responseStatus": "ERROR",
decision is already made for the account "error": {
"code": "BUSINESS_RULE_E
made for the
RROR",
account "description": "Previous CE
request for this application is in
progress"
}
}

400 Invalid Request Body One of the validation errors *Scenarios under which
occurred. status code of 400 is
returned are described is
separate table below
500 Bad Gateway / An internal error from the server *Scenarios under which
Internal Server Error side. status code of 500 is
returned are described is
separate table below

*Scenarios under which status code of 400 is returned with an error message –

HTTPS Code Response Type Meaning Response Body

400 Invalid Request Json not in conformation with {
Body schema. "responseStatus": "ERROR",
"error": {
"code": "BAD_REQUEST",
"description": "dob missing",
"errorType": "INVALID_PAYLOAD"
}
}

400 Invalid Request Invalid text field characters. {

Body "responseStatus": "ERROR",
"error": {
"code": "BAD_REQUEST",
"description": "dob is not valid",
"errorType": "INVALID_PAYLOAD"
}
}

*Scenarios under which status code of 500 is returned with an error message –

HTTPS Code Response Type Meaning Response Body

500 Internal Server Internal Server Error occurred {“responseStatus”: “ERROR”,
Error due to Bad Gateway or the “error”:
 server failed to respond with a { “code”:”INTERNAL_SERVER_ERROR
valid json response. ”, “description”: “Something went
wrong” }
}

Callbacks:

Successful callback
{
"status": "200",
"is_retryable”: false,
"message": "success",
"data":
{
"account_id": "PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
"abfl_application_id": "B2B000000000001",
"loan_amount": "10000",
"roi": "NA",
"tenure": "12",
"ccc_id": "123456",
"risk_flag": "LOW",
"pep_flag": "FALSE"
}
}

Call Back Response Table

Parameter Name Value

status Status code

is_retryable true/false
message Success / actual error
account_id Partners Unique application ID
async_id ABFL internal async ID
abfl_application_id ABFL internal application ID
loan_amount Actual loan amount
Roi Actual ROI
tenure tenure
ccc_id ABFL Unique customer ID which will be utilized
for other APIs
risk_flag LOW
pep_flag FALSE

Rejected callback.
{
"status": "412",
"is_retryable":false,
"message": "Rejected in ELMS API",
"data": {
"account_id": " PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}

Got unexpected response from Bureau. We will process this request separately.
{
"status": "202",
"is_retryable”: false,
"message": "Errors encountered with Bureau -Resolution WIP. Next update within 72 hours.",
"data": {
"account_id": " PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}

Validation Error response from Bureau

{
"status": "400",
"is_retryable”: true,
"message": "invalid request",
"data": {
"account_id": "PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}

Max Retry Exceeded:

{
"status": "508",
"is_retryable”: true,
"message": "Max retry limit for unscr API exhausted",
"data": {
"account_id": " PARTNERID1000001",
"async_id": "PTM20210607123456789abcdef",
}
}