REST APIs
These APIs are called from the server side. The workflow is as follows:
- First a user is created by calling Create User API
- Eligibility for the given user is checked by calling Get Eligibility API
- Token is generated for the user by calling Generate Token API and is sent to the Android app to be used with the SDK
#
AuthenticationAll the APIs below require a Server API Key to be passed in x-api-key
header. This API Key will be shared directly by FinBox. Make sure this key is not exposed in any of your client side applications.
#
Postman CollectionPostman collection for the REST APIs can be downloaded using the button below:
Postman environment having base_url
and server-api-key
will be shared separately.
#
Request and Response formatsAll APIs accept request body with application/json
content type, the response body is as follows:
On successful response you'll receive 200 HTTP status, with status
value as true
.
On failure, response will have status
key as false
, and error
will hold the message indicating the failure.
#
Create UserThis API creates a FinBox lending user for a given customer ID.
Endpoint
POST base_url
/v1/user/create
#
Request Format#
Response#
Error CasesCase | HTTP Code |
---|---|
Missing customerID | 403 |
Missing mobile number | 403 |
Invalid mobile number | 403 |
User already exists | 409 |
#
Get EligibilityThis API checks for a user's eligibility and returns the eligible amount. Partner platform data and data from DeviceConnect SDK is used to prequalify the customers. The customer_id
in DeviceConnect SDK should be same as the customer_id
of user.
![Prequalification API Workflow](/img/api-workflow-prequalification.jpg)
Endpoint
GET base_url
/v1/user/eligibility?customerID=somecustomerid
#
ResponseHere is_eligible
is a boolean indicating whether the user is eligible or not, while eligibility_amount
is a float that indicates the loan eligibility amount.
#
Error CasesCase | HTTP Code |
---|---|
Missing customerID | 403 |
User not found | 400 |
User does not have eligibility data | 409 |
#
Generate TokenThis API can be called multiple times for an eligible user, and is used to get a valid token that can be used by the Android App to initialize the SDK.
Token Validity
- In case of production environment, the token is valid for 24 hours and in UAT it is valid for 1 week.
- It is recommended to call this API everytime user clicks on the banner on app, so that a fresh token is issued for the user session everytime.
Endpoint
POST base_url
/v1/user/token
#
Request Format#
ResponseHere token
field indicates the token.
#
Error CasesCase | HTTP Code |
---|---|
Missing customerID | 403 |
User does not exist | 404 |
User eligibility not available | 400 |
User not eligible for loan | 403 |
Tracking Source
In case you are using same API key across different platforms, and want to track the source of the user, also pass a string field source
in the request body, indicating a unique source from which the user is accessing the SDK from.
#
List UsersLists all the users created from a given sourcing entity's account. It's a paginated API.
Endpoint
GET base_url
/v1/users?limit=totalRecords
&page=numPages
#
Query ParametersQuery parameters can be appended at end of the URL like /?limit=20&page=1
Parameter | Optional | Type | Description |
---|---|---|---|
limit | Yes | Number | Records Per Page. Default Value is 10 |
page | Yes | Number | Page Number. Default Value is 1 |
from | Yes | Date | Filter by a given start date (IST). Defaults to beginning of time. Format yyyy-mm-dd . Needs to be used with query param to |
to | Yes | Date | Filter by a given end date (IST). Defaults to current date. Format yyyy-mm-dd . Needs to be used with query param from |
customerID | Yes | String | Filter all users of a given %customerID% pattern. |
mobile | Yes | String | Filter all users of a given %mobileNumber% pattern. |
statusText | Yes | String | Filter all loan applications of a given loan status. Status list in Appendix |
#
ResponseDifferent values of user status can be found in Appendix
#
User ProfileReturns the profile of the user against a customerID
Endpoint
GET base_url
/v1/user/profile?customerID=someCustomerID
#
Response- Different values of
status
(customer status) can be found in Appendix createdAt
indicates the date time of user creation inYYYY-MM-DD HH:MM:SS
format (UTC)
#
List LoansLists all the loan applications created from a given sourcing entity's account. It's a paginated API.
Endpoint
GET base_url
/v1/loans?limit=totalRecords
&page=numPages
#
Query ParametersQuery parameters can be appended at end of the URL like /?limit=20&page=1
Parameter | Optional | Type | Description |
---|---|---|---|
limit | Yes | Number | Records Per Page. Default Value is 10 |
page | Yes | Number | Page Number. Default Value is 1 |
from | Yes | Date | Filter by a given start date (IST). Defaults to beginning of time. Format yyyy-mm-dd |
to | Yes | Date | Filter by a given end date (IST). Defaults to current date. Format yyyy-mm-dd |
customerID | Yes | String | Filter all loan applications of a given %customerID% pattern. |
mobile | Yes | String | Filter all loan applications of a given %mobileNumber% pattern. |
statusText | Yes | String | Filter all loan applications of a given loan status. Status list in Appendix |
#
ResponseDifferent values of loan status can be found in Appendix
createdAt
indicates the date time of loan creation in YYYY-MM-DD HH:MM:SS
format (UTC)
#
Loan DetailsReturns the details of a given loan application.
Endpoint
GET base_url
/v1/loan/details?loanApplicationID=someLongLoanApplicationUUID
#
ResponseMost of the parameters of the response are self-explainatory. Some key fields are explained below:
| Field | Description |
| - | - |
| loanApplicationNum | A readable loan number format is FBxxx |
| appliedLoanAmount | The amount of loan applied by the user. Note that it might be different from the final loan offer |
| residenceType | Type of residence - Rented or Owned |
| accountHolderName | Verified name as per user's bank account |
| dob | Date of Birth in YYYY-MM-DD
format |
| createdAt | Date time of loan creation in YYYY-MM-DD HH:MM:SS
format (UTC) |
| loanFormData | Fields in this key varies for every sourcing entity, exact keys will be shared for this during the integration |
#
Loan OffersReturns the loan offers made to a given loan application.
NOTE
Loan Offers API works only once loan is approved
Endpoint
GET base_url
/v1/loan/offers?loanApplicationID=someLongLoanApplicationUUID
Response fields are explained below:
| Field | Type | Description |
| - | - | - |
| amount | Float | Loan Amount |
| tenureMonths | Integer | Tenure in Months |
| annualInterest | Float | Annual Interest Rate in Percentage |
| processingFee | Float | Processing Fee |
| gst| Float | GST Percentage |
| advanceEMIAmount | Float | Advance EMI Amount |
| emiCalculationMethod | String | Can be flat_rate
or reducing_balance
|
| status | String | Can be offer_accepted
or offered
|
| disbursalAmount | Float | Final Disbursal Amount |
| totalPayableAmount | Float | Total Payable Amount |
| emis | Array of Objects | Contains emi objects containing date and amount sorted in sequence of installments |
| emiAmount | Float | Tells the EMI Amount |
| emiDate | String | Contains YYYY-MM-DD
format |
#
Get Signed AgreementReturns the presigned url for signed agreement PDF File
NOTE
- This API works only after
loan_signed_agreement_generated
event has been triggered - The presigned URL in response is valid for 300 seconds
Endpoint
GET base_url
/v1/loan/agreement?loanApplicationID=someLongLoanApplicationUUID
#
Loan RepaymentsReturns the repayments information for a given loan application.
NOTE
Loan Repayments API works only after loan disbursal.
Endpoint
GET base_url
/v1/loan/repayments?loanApplicationID=someLongLoanApplicationUUID
Response fields are explained below:
| Field | Type | Description |
| - | - | - |
| lenderName | String | Lender Name |
| loanPaymentID | String | A UUID identifying an installment |
| amount | Float | EMI amount |
| installmentNum | Integer | Instalment number varies from 1 to tenureMonths
(from loan offer API) |
| lateCharge | Float | Late charge (if any otherwise 0) |
| status | String | Can be PAID
, UNPAID
or PENDING
|
| dueDate | String | Due date for the installment in YYYY-MM-DD
format |
| paidDate | String | Date of payment in YYYY-MM-DD
format, if not paid the value is blank string ""
|
| totalPayable | Float | Total amount to be paid by user, excluding partial payments made |
| amountReceived | Float | Denotes the amount paid by customer against the EMI |
#
EDIIn case the loan product involves EDI (daily installments), you'll get an additional ediInfo
key in response.
Sample Response
EDI Keys: | Field | Type | Description | | - | - | - | | amountPerDay | Float | EDI Amount to be paid per day | | totalEDIs | Integer | Number of EDIs to be paid | | edisPaid | Integer | Number of EDIs fully paid |
#
Repay LoanMarks the repayment of a given loan EMI
NOTE
This API is disabled by default. If required, request FinBox team to enable this API.
Endpoint
POST base_url
/v1/loan/repay
#
Request FormatResponse Format
#
Credit Line DetailsReturns credit line details for a given user using the customerID
Endpoint
GET base_url
/v1/creditline/details?customerID=someCustomerID
Response Format
Response fields are explained below:
| Field | Type | Description |
| - | - | - |
| status | String | Status of credit line, can be ACTIVE
or INACTIVE
|
| maxLimit | Float | Maximum credit limit assigned to the user |
| availableLimit | Float | Currently available limit of the user |
| validity | String | Indicates the expiry date of credit line in YYYY-MM-DD
|
| inactiveReason | String | Reason for status to be INACTIVE
|
#
Error CasesCase | HTTP Code |
---|---|
Missing customerID | 403 |
user with credit line not found | 404 |
#
Credit Line TransactionsReturns credit line transactions for a given user using the customerID
Endpoint
GET base_url
/v1/creditline/transactions?customerID=someCustomerID
Response Format
Response fields are explained below:
| Field | Type | Description |
| - | - | - |
| txnID | String | Unique Transaction ID generated by FinBox |
| partnerTxnID | String | Transaction ID passed on Client SDK |
| invoiceNo | String | Invoice No for the transaction |
| txnStatus | String | Status of transaction can be PROCESSING
, CONFIRMED
, DISBURSED
, PAID
, CANCELLED
, OVERDUE
|
| amount | Float | Transaction amount |
| interest | Float | Annual Interest Percentage user is paying for this transaction |
| subventionAmount | Float | Subvention amount on this transaction |
| processingFee | Float | Processing Fee on this transaction |
| gst | Float | Indicates GST in percentage |
| disbursalAmount | Float | Indicates the final amount that will be disbursed |
| emiCalculationMethod | String | Can be flat_rate
or reducing_balance
|
| createdAt | String | Transaction creation time in YYYY-MM-DD HH:MM:SS
format |
| disbursalUTR | String | UTR number of disbursal made by lender |
objects in emis
contain:
| Field | Type | Description |
| - | - | - |
| amount | Float | Indicates the EMI Amount |
| installmentNum | Integer | Installment Number |
| charges | Array of objects | Contains array of different charges, possible chargeType
are LATE_CHARGE
, NACH_BOUNCE_CHARGE
, LATE_INTEREST_CHARGE
|
| status | String | Payment status can be UNPAID
, PAID
, PENDING
|
| dueDate | String | Due date in YYYY-MM-DD
format |
| paidDate | String | Payment completion in YYYY-MM-DD
format, if not paid is blank string ""
|
| totalPayable | Float | Total payable amount for the EMI |
filter basis of partnerTxnID
You can also pass an optional field, partnerTxnID
as query string parameter to filter out transactions basis of specified partnerTxnID
, as follows:
base_url
/v1/creditline/transactions?customerID=someCustomerID
&partnerTxnID=AZ123ABC
charges
Different meanings of charges are as follows:
LATE_CHARGE
: late fee added because of late in EMI paymentLATE_INTEREST_CHARGE
: total day wise interest added due to EMI payment delayNACH_BOUNCE_CHARGE
: this is added if nach was presented, but bounced
emis key
Array of objects in emis
will be empty in case of CANCELLED
and PROCESSING
transactions.
#
Error CasesCase | HTTP Code |
---|---|
Missing customerID | 403 |
user with credit line not found | 404 |
#
Confirm Credit Line TransactionConfirms Credit Line Transaction in processing state
NOTE
- This API's request format is specific to e-commerce use case, and is disabled by default for clients with a different use case.
- For other use cases, FinBox team will share a different API for updating the status.
Endpoint
POST base_url
/v1/creditline/txn/confirm
Request Format
Field | Type | Description |
---|---|---|
txnID | String | Unique FinBox Transaction ID, this can be fetched using the Credit Line Transactions API |
awbNo | String | Air Waybill Number |
invoiceNo | String | Invoice Number |
podExtension | String | File extension for proof of delivery, can be jpg , png or pdf |
podBase64 | String | Base 64 encoded file content of proof of delivery |
invoiceExtension | String | File extension for invoice, can be jpg , png or pdf |
invoiceBase64 | String | Base 64 encoded file content of invoice |
On successful updating the status, API will give a response with 200 HTTP status code.
#
Error CasesCase | HTTP Code |
---|---|
Missing txnID | 403 |
Any other missing field | 400 |
Invalid extension | 400 |
Error decoding base 64 string | 400 |
Error processing file | 400 |
txnID not found | 404 |
only transaction with status PROCESSING can be updated | 403 |
#
Cancel Credit Line TransactionCancels Credit Line Transaction in processing state
Endpoint
POST base_url
/v1/creditline/txn/cancel
Request Format
Field | Type | Description |
---|---|---|
txnID | String | Unique FinBox Transaction ID, this can be fetched using the Credit Line Transactions API |
On successful updating the status, API will give a response with 200 HTTP status code.
#
Error CasesCase | HTTP Code |
---|---|
Missing txnID | 403 |
txnID not found | 404 |
only transaction with status PROCESSING can be updated | 403 |
#
Split Credit Line TransactionSplits Credit Line Transaction in processing state into different transactions. Useful when same order has different invoices, shipment or deliveries. After splitting, each transaction can further be splitted or moved to cancelled / confirmed state.
NOTE
- This API's request format is specific to e-commerce use case, and is disabled by default for clients with a different use case.
- For other use cases if this is required, FinBox team will share a different API.
Endpoint
POST base_url
/v1/creditline/txn/split
Request Format
Field | Type | Description |
---|---|---|
txnID | String | Unique FinBox Transaction ID, this can be fetched using the Credit Line Transactions API |
invoiceNo | String | Invoice Number. This is optional and can be skipped by passing blank string |
amount | Float | Amount of the sub transaction |
On successful updating the status, API will give a response with 200 HTTP status code.
NOTE
- Please make sure sum of amounts add up to the original transaction amount being split
- API will throw an error if total amount exceeds the original transaction amount being split
- In case sum of amounts is less than original transaction amount, another transaction with no invoiceNo and left over amount will be created, and split will proceed
- After split is complete sub transactions will have same
partnerTxnID
but differenttxnID
(FinBox Transaction ID). In such cases,invoiceNo
andamount
fields in Credit Line Transactions API can be used to distinguish between the sub transactions.
#
Error CasesCase | HTTP Code |
---|---|
Missing txnID | 403 |
txnID not found | 404 |
only transaction with status PROCESSING can be splitted | 403 |
amount should be greater than 0 | 400 |
sum of invoice amounts cannot exceed transaction amount | 400 |
#
User Activity HistoryReturns the activity
Endpoint
GET base_url
/v1/user/activity?customerID=someCustomerID
#
ResponseentityType
indicates who took the action eventeventType
indicates the active event or activitysource
indicates the last source passed in Generate Token API or Session APIjourneyType
can bebusiness_loan
,personal_loan
orcredit_line
A list of all possible activities (eventType
) can be found Appendix
A list of all possible entity types (entityType
) can be found Appendix
#
WebhookA webhook can be configured to receive events on different actions taken throughout the user journey.
To configure this, you can update the webhook URL in Settings page of FinBox Dashboard. The webhook URL should be a valid endpoint.
A Valid Endpoint:
- receives a POST request
- receives a request body with content-type
application/json
- returns a 2xx status code on successful reception.
We'll be sending JSON encoded body in the following payload format:
Retries and Timeout
- If the webhook endpoint gives a non 2xx HTTP status code, or if the API call fails, then maximum 3 times retry is attempted (maximum 4 attempts) with exponential backoff.
- Every webhook endpoint call has a timeout set of maximum 90 seconds.
IMPORTANT
loanApplicationID
is available once the loan application is created, and will not be available for credit line specific activities.eventDescription
is always a string, in some cases you might get string encoded JSON as well. These specific cases are mentioned in Appendix along with activities.source
indicates the last source passed in Generate Token API or Session APIjourneyType
can bebusiness_loan
,personal_loan
orcredit_line
A list of all possible activities (eventType
) can be found Appendix
A list of all possible entity types (entityType
) can be found Appendix