projects.apps.loans

Overview

The Loans API allows you to:

  • View, create and manage loan accounts.

  • Make loan repayments.

  • Make loan disbursements.

{
   "accountId": string,
   "accountNo": number,
   "loanType": string,
   "borrowerId": string,
   "lenderId": string | null,
   "category": string,
   "sequenceNo": number,
   "productId": string,
   "contract": object(LendingContract),
   "loanAmount": number,
   "balances": object(LoanBalances),
   "startDate": string,
   "maturityDate": string,
   "schedule": object(LoanSchedule) | null,
   "settlementDate": string | null,
   "status": number,
   "performanceStatus": number,
   "result": object(LoanOutcome) | null,
   "assessmentId": string,
   "appVersionId": string,
   "requestId": string,
   "settings": object(LoanSettings) | null,
   "labels": object(Labels) | null,
}

Fields

Field

Data Type

Description

accountId

string

Required A string that uniquely identifies the loan account within the lending app.

Read-only after creation

accountNo

number

Required. Used in responses only. A globally unique numeric identifier for the loan account.

Read-only after creation

loanType

string

Required The loan type. It is synonymous with the lending product type for the loan.

Read-only

borrowerId

string

Id of the borrower that holds the loan account.

Read-only after creation

lenderId

string | null

Required

Id of the lender that owns the account.

Read-only after creation

category

string (

'individual', 'company'

)

Required

Loan account category. It is synonymous with the borrower account category.

Read-only after creation

sequenceNo

number

Required. Used in responses only. Indicates the account's position in the list of ordered loans for a borrower. It is equal to the number of loan accounts attached to the current borrower plus 1.

Read-only after creation

productId

string

Required

The uid or productId of the LendingProduct used to build the loan's contract.

Read-only after creation

contract

object

( LendingContract )

Required

The lending contract used to create the loan.

Read-only after creation

loanAmount

number

Required The loan principal amount.

Read-only after creation

balances

object

( LoanBalances )

Required The loan account's balances. These will change whenever an adjustment is done on the account.

Read-write

startDate

string

( Timestamp format )

Required. The loan account's start date as per the contract. It is expressed in ISO format.

Read-write

maturityDate

string

( Timestamp format )

The date that the loan account is expected to be fully settled as per the contract. It is expressed in ISO format.

Read-write

status

number

( LendingAccountState )

Loan account status.

Read-write

schedule

object

( LoanSchedule )

Loan schedule information.

Read-write

settlementDate

string

( Timestamp format )

| null

The date that the loan account was fully settled as per the contract. It is expressed in ISO format.

Read-write

requestId

string

The GetOffers requestId used to create this loan account.

Read-only

assessmentId

string | null

The credit assessment id that was used to create the loan.

Read-only

appVersionId

string | null

The lending app versionId used to process this event. Read more about app versions here.

Example: v1

Read-only

performanceStatus

number

Used in responses only.

Indicates an open loan account's current performance as per the contract.

Read-only

settings

object

( LoanSettings ) | null

Loan settings.

Read-write

result

object

( LoanOutcome ) | null

Used in responses only. The loan outcome. It’s set to null on creation of the account and is populated with the outcome after the account is closed.

Read-only

labels

object ( Labels )

| null

Custom loan account labels.

Read-write

List

GET https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/loans

List all loan accounts for a lending app.

Path Parameters

NameTypeDescription

projectId

string

Id of the weza.io project

appId

string

Id of the lending app

Query Parameters

NameTypeDescription

order

string

Describes how to order the results. The value can be either asc or desc. Defaults to asc.

filter

string

An expression to filter the results of the request. The following fields can be used to filter loans. - accountId - accountNo - loanType - borrowerId - status - appVersionId - assessmentId - performanceStatus

pageToken

string

The nextPageToken value returned from a previous list call (if any). It should always be encoded.

pageSize

string

Maximum results per page. Defaults to 1000.

Headers

NameTypeDescription

Authorization

string

Bearer token

{
	"assessments": [{
			"uid": "c78e30a6-3136-5762-84a0-24e8ef895e7a",
			"name": "projects/test-project/apps/testapp/assessments/826d69a1-4fc1-54b1-b17e-c6b6684dd9da",
			"status": 0,
			"createdAt": "2020-09-21T19:32:26.889Z",
			"assessmentId": "826d69a1-4fc1-54b1-b17e-c6b6684dd9da",
			"appVersionId": "v5",
			"accountId": "borrower:10023",
			"assessmentType": "projects/test-project/apps/testapp/assessmentTypes/personal_credit_standard",
			"timestamp": "2020-09-19T18:00:00.000Z",
			"result": null,
			"requestId": "cfcd029e6c"
		},
		{
			"uid": "d22bdce6-2585-5182-bcc3-ad80e6a401be",
			"name": "projects/test-project/apps/testapp/assessments/b3a760ae-21f0-5cf5-897e-ebb9e5ce51b9",
			"status": 0,
			"createdAt": "2020-09-21T19:08:26.402Z",
			"assessmentId": "b3a760ae-21f0-5cf5-897e-ebb9e5ce51b9",
			"appVersionId": "v5",
			"accountId": "borrower:10023",
			"assessmentType": "projects/test-project/apps/testapp/assessmentTypes/personal_credit_standard",
			"timestamp": "2020-09-19T18:00:00.000Z",
			"result": null,
			"requestId": "3280fa70b6"
		},
		{
			"uid": "1ca0f016-1233-5d2f-84e0-195ed77de974",
			"name": "projects/test-project/apps/testapp/assessments/af621617-151b-5933-8ae2-6538c7ab0ff8",
			"status": 0,
			"createdAt": "2020-09-21T18:57:22.946Z",
			"assessmentId": "af621617-151b-5933-8ae2-6538c7ab0ff8",
			"appVersionId": "v5",
			"accountId": "borrower:10023",
			"assessmentType": "projects/test-project/apps/testapp/assessmentTypes/personal_credit_standard",
			"timestamp": "2020-09-19T18:00:00.000Z",
			"result": null,
			"requestId": "721775eea2"
		},
		{
			"uid": "441cd582-b742-5bae-bfce-276cd0c5ecb2",
			"name": "projects/test-project/apps/testapp/assessments/7ec81719-e0b6-541c-bbe7-1dbc4bf984f8",
			"status": 0,
			"createdAt": "2020-09-21T16:00:27.230Z",
			"assessmentId": "7ec81719-e0b6-541c-bbe7-1dbc4bf984f8",
			"appVersionId": "v5",
			"accountId": "borrower:10023",
			"assessmentType": "projects/test-project/apps/testapp/assessmentTypes/personal_credit_standard",
			"timestamp": "2020-09-19T18:00:00.000Z",
			"result": null,
			"requestId": "2b18e7c83a"
		},
		{
			"uid": "11135a22-8f74-52b7-920e-ec63f7346b1c",
			"name": "projects/test-project/apps/testapp/assessments/f21962cf-929d-596e-9343-4f5c436a6cbb",
			"status": 0,
			"createdAt": "2020-09-20T20:06:54.662Z",
			"assessmentId": "f21962cf-929d-596e-9343-4f5c436a6cbb",
			"appVersionId": "v5",
			"accountId": "borrower:10023",
			"assessmentType": "projects/test-project/apps/testapp/assessmentTypes/personal_credit_standard",
			"timestamp": "2020-09-19T18:00:00.000Z",
			"result": null,
			"requestId": "c9c46ea15f"
		},
		{
			"uid": "4df0f896-db15-50e2-b821-bed8d9afba3a",
			"name": "projects/test-project/apps/testapp/assessments/5b2f4bf6-d9ce-539d-a4c2-2aba1041d764",
			"status": 2,
			"createdAt": "2020-08-07T18:28:25.743Z",
			"assessmentId": "5b2f4bf6-d9ce-539d-a4c2-2aba1041d764",
			"appVersionId": "v2",
			"accountId": "borrower:10023",
			"assessmentType": "assessmentTypes/personal_credit_standard",
			"timestamp": "2020-06-27T12:00:00.000Z",
			"result": {
				"rule": "scorecard",
				"type": "invalid",
				"reason": null,
				"message": "An unknown error occurred while processing this request."
			},
			"requestId": null
		},
		{
			"uid": "88a8f009-eb04-5f93-9bca-97cdd35b1860",
			"name": "projects/test-project/apps/testapp/assessments/762cb251-d952-52cb-9377-2e419ce71ce8",
			"status": 2,
			"createdAt": "2020-07-21T17:09:42.857Z",
			"assessmentId": "762cb251-d952-52cb-9377-2e419ce71ce8",
			"appVersionId": "v1",
			"accountId": "borrower:10023",
			"assessmentType": "assessmentTypes/personal_credit_standard",
			"timestamp": "2020-06-28T12:00:00.000Z",
			"result": {
				"rule": "lending.denyLowDataCounts",
				"type": "invalid",
				"reason": "no_data",
				"message": "There was not enough data found for this lending account. Confirm your app events are being received & processed successfully on weza.io."
			},
			"requestId": null
		}
	],
	"nextPageToken": null
}

Request Body

The request body should be empty.

Response Body

If successful, the response will contain data with the following structure.

{
  "loans": [
    {
      object(Loan)
    }
  ],
  "nextPageToken": string,
}

Fields

Field

Data Type

Description

loans[]

object(Loan)

A list of loan instances.

nextPageToken

string

Token to use to fetch the next page of data if any.

Authorization

Requires one of the following OAuth scopes:

  • platform.lending

  • platform.lending:read

The authenticated user must have the lending.loans.list permission.

Create

POST https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/loans

Create a loan account if one doesn't exist.

Path Parameters

NameTypeDescription

appId

string

Id of the lending app

projectId

string

Id of the weza.io project

Headers

NameTypeDescription

Authorization

string

Bearer token

Request Body

The request body contains an instance of Loan.

Response Body

The response body contains a new instance of Loan.

Authorization

Requires one of the following OAuth scopes:

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.loans.create permission.

Get

GET https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/loans/:accountId

Retrieve a loan by id.

Path Parameters

NameTypeDescription

projectId

string

Id of the weza.io project

appId

string

Id of the lending app

accountId

string

accountId or uid value

Headers

NameTypeDescription

Authorization

string

Bearer token

Response Body

The response body contains an instance of Loan.

Authorization

Requires one of the following OAuth scopes:

  • platform.lending

  • platform.lending:read

The authenticated user must have the lending.loans.get permission.

Delete

DELETE https://lending.wezaapis.com/v1/projects/:projectId/apps/:appId/loans/:accountId

Delete a loan account by id. You cannot delete an account whose state is either open or closed.

Path Parameters

NameTypeDescription

projectId

string

Id of the weza.io project

appId

string

Id of the lending app

accountId

string

accountId or uid value

Headers

NameTypeDescription

Authorization

string

Bearer token

Response Body

The response body is empty.

Authorization

Requires one of the following OAuth scopes:

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.loans.delete permission.

MakeRepayment

POST https://lending.wezaapis.com/v1/projects/{projectId}/apps/{appId}/loans/{accountId}:makeRepayment

Make a loan repayment. You cannot only make a repayment for an account whose state is open.

Path Parameters

NameTypeDescription

projectId

string

Id of the weza.io project

appId

string

Id of the lending app

accountId

string

accountId or uid value

Headers

NameTypeDescription

Authorization

string

Bearer token

# Request

curl --location --request POST 'https://lending.wezaapis.com/v1/projects/test-project/apps/testapp/loans/2576645010869-1-1/makeRepayment' \
--header 'Authorization: Bearer 4beee2e5b5d5a316ca07e8f05659c8a82acc6c80' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transactionDate": "2020-09-30T05:00:00Z",
    "valueDate": "2020-09-30T05:00:00Z",
    "amount": 1032,
    "externalId": "MPEIED22921",
    "channel": "mobile",
    "network": "mpesa",
    "currencyCode": "KE",
    "notes": null
}'

# Response

{
    "uid": "3bf172da-dd14-5d68-8f01-d78c396f4642",
    "name": "projects/test-project/apps/testapp/loans/2576645010869-1-1",
    "status": 2,
    "createdAt": "2020-09-27T16:58:43.380Z",
    "accountId": "2576645010869-1-1",
    "accountNo": 1536369909650,
    "loanType": "loan",
    "category": "individual",
    "borrowerId": "10023",
    "lenderId": null,
    "sequenceNo": 1,
    "productId": "21_day_loan_3_repayments",
    "contract": {
        "terms": {
            "fees": [
                {
                    "kind": "deducted_disbursement_fee",
                    "value": 0.02,
                    "required": true,
                    "description": "Origination fee of 2% of the loan principal amount.",
                    "displayName": "2% Origination Fee",
                    "calculationMethod": "principal_amount_ratio",
                    "installmentTarget": "first_in_sequence",
                    "calculateInAdvance": true
                },
                {
                    "kind": "late_payment_fee",
                    "value": 0.02,
                    "required": true,
                    "description": "A fee of 2% of the loan principal amount that is charged when an installment payment is late.",
                    "displayName": "2% Late Payment Fee",
                    "calculationMethod": "principal_amount_ratio",
                    "installmentTarget": "in_progress",
                    "calculateInAdvance": false
                }
            ],
            "period": "21 days",
            "penalty": {
                "rate": 0.02,
                "gracePeriod": "2 days",
                "calculationMethod": "overdue_principal"
            },
            "interest": {
                "maxAER": 15,
                "maxAPR": 15,
                "baseRate": 0.15,
                "waiverRate": 0,
                "riskPremiumRate": 0.16,
                "calculationMethod": "reducing_balance",
                "compoundingPeriod": "7 days"
            }
        },
        "amounts": {
            "fees": 20,
            "penalty": 0,
            "interest": 12,
            "principal": 1000,
            "repayment": 1032,
            "requested": 1000,
            "disbursement": 980
        },
        "tranches": [
            {
                "amount": 980,
                "dueDate": "2020-09-27T23:59:59.999Z",
                "startDate": "2020-09-27T00:00:00.000Z",
                "sequenceNo": 1
            }
        ],
        "productId": "21_day_loan_3_repayments",
        "startDate": "2020-09-27T00:00:00.000Z",
        "versionNo": 1,
        "adjustments": [
            {
                "kind": "deducted_disbursement_fee",
                "value": 20,
                "action": "deduct",
                "source": "principal",
                "target": "disbursement",
                "valueType": "absolute",
                "description": "Origination fee of 2% of the loan principal amount.",
                "displayName": "2% Origination Fee"
            }
        ],
        "installments": [
            {
                "amounts": {
                    "fees": 20,
                    "penalty": 0,
                    "interest": 6,
                    "principal": 331,
                    "repayment": 357
                },
                "dueDate": "2020-10-04T23:59:59.999Z",
                "startDate": "2020-09-27T00:00:00.000Z",
                "sequenceNo": 1
            },
            {
                "amounts": {
                    "fees": 0,
                    "penalty": 0,
                    "interest": 4,
                    "principal": 333,
                    "repayment": 337
                },
                "dueDate": "2020-10-11T23:59:59.999Z",
                "startDate": "2020-10-04T00:00:00.000Z",
                "sequenceNo": 2
            },
            {
                "amounts": {
                    "fees": 0,
                    "penalty": 0,
                    "interest": 2,
                    "principal": 336,
                    "repayment": 338
                },
                "dueDate": "2020-10-18T23:59:59.999Z",
                "startDate": "2020-10-11T00:00:00.000Z",
                "sequenceNo": 3
            }
        ],
        "maturityDate": "2020-10-18T23:59:59.999Z",
        "interestRates": {
            "AER": 0.3622,
            "APR": 0.5562,
            "APY": 0.3622,
            "nominalRate": 0.31,
            "periodicRate": 0.006
        }
    },
    "loanAmount": 1000,
    "balances": {
        "fees": {
            "due": 0,
            "paid": 20,
            "total": 20,
            "unpaid": 0,
            "overdue": 0
        },
        "penalty": {
            "due": 0,
            "paid": 0,
            "total": 0,
            "unpaid": 0,
            "overdue": 0
        },
        "interest": {
            "due": 0,
            "paid": 12,
            "total": 12,
            "unpaid": 0,
            "overdue": 0
        },
        "principal": {
            "due": 0,
            "paid": 1000,
            "total": 1000,
            "unpaid": 0,
            "overdue": 0
        },
        "repayment": {
            "due": 0,
            "paid": 1032,
            "total": 1032,
            "unpaid": 0,
            "overdue": 0
        }
    },
    "startDate": "2020-09-27T00:00:00.000Z",
    "maturityDate": "2020-10-18T23:59:59.999Z",
    "performanceStatus": 1,
    "schedule": {
        "daysLate": 0,
        "nextInstallment": null
    },
    "settlementDate": "2020-09-30T05:00:00.000Z",
    "result": {
        "type": "settled_early",
        "reason": null,
        "message": null
    },
    "settings": null,
    "assessmentId": "20c237c9-b200-5dd8-9922-18bdef2aa5d7",
    "appVersionId": "v7",
    "labels": null,
    "requestId": "bf9aa5672b"
}

Request Body

The request body should contain the following parameters.

Parameter

Data Type

Description

externalId

string

The id of the repayment transaction from the payments network.

amount

number

Repayment amount.

transactionDate

string

( Timestamp format )

The real world date of the repayment transaction in ISO format.

valueDate

string

( Timestamp format )

The actual date that the payment will take effect on the account in ISO format.

It defaults to the transactionDate value if left unspecified.

channel

string ( 'web', 'mobile', 'physical' ) | null

The payment channel type.

network

string | null

The name of the payment network.

currencyCode

string | null

The currency code.

notes

string | null

Transaction notes.

Response Body

The response body contains an instance of Loan.

Authorization

Requires one of the following OAuth scopes:

  • platform.lending

  • platform.lending:write

The authenticated user must have the lending.loans.makeRepayment permission.

Previousprojects.apps.assessmentsNextTypes

Last updated