Limits

Use this endpoint to request for a customer's credit limit. For new customers a limits object will be created. For existing customers, we will simply return their credit limit details. You're required to provide KYC details (customer's personal and occupational info). This information is used to credit score the customer.

The limits object

Personal Details Attributes

AttributeData typeRequiredDescription
first_namestringtrueThe customer's first name as per their ID
last_namestringtrueThe customer's second name as per their ID
id_numberstringtrueThe customer's ID number
country_codestringtrueISO 3166-1 2-letter or 3-letter country code
phone_numberstringtrueThe customer's mobile number
employedbooleantrueSet to true id the customer is employed, if they are self-employed set to false
genderstringtrueCustomer's gender should be either male or female
date_of_birthstringtrueCustomer's date of birth as per their ID, the format mm/dd/yyyy
marital_statusstringtrueCustomer's marital status should be either single or married
emailstringtrueCustomer's email address
loan_amountintegertrueThe cart value or payment amount the customer requires to complete the transaction
referral_sourcestringtrueThis refers to the store key that will be sent to the partner with api credentials
note

Apart from the attributes above you should also append the customer's occupational details depending on whether they are employed or self-employed.

Occupational Details Attributes

AttributeData typeRequiredDescription
employerstringtrueName of the customer's employer.
net_incomeintegertrueThe customer's monthly net income.
expensesintegertrueThe customer's monthly expenses
job_levelstringtrueSeniority level of the customer at their place of work. Possible values:
  1. Intern
  2. Associate
  3. Junior Manager
  4. Mid level manager
  5. Senior Manager
  6. Executive Manager
job_functionstringtrueIndustry in which the customer works in. Possible values:
  1. Accounting Auditing & Finance
  2. Administrative & Office
  3. Agriculture &Farming
  4. Building & Architecture
  5. Community & Social Services
  6. Consulting and Strategy
  7. Creative & Design
  8. Customer service & Support
  9. Employability & Soft Skills
  10. Engineering
  11. Food sciences & catering
  12. Health & Safety
  13. Hospitality/Leisure & Travel
  14. Human Resources
  15. IT & Software
  16. Legal Services
  17. Management & Business Development
  18. Marketing & Communication
  19. Medical & Pharmaceutical
  20. Natural sciences
  21. Project & Product management
  22. Quality Control & Assurance
  23. Real estate & Property Management
  24. Research/Teaching/Training
  25. Sales
  26. Security
  27. Supply Chain & Development
  28. Trade & Services
  29. Transport & Logistics
  30. Other
employer_sectorstringtrueWorks in private_sector or government_sector ?
payment_typestringtrueHow the customer receives their salary. Possible values:
  1. bank
  2. mpesa
  3. cash

Occupational Details Attributes (Self Employed)

AttributeData typeRequiredDescription
business_typestringtrueThe organizational classification of the customer's business. Possible values:
  1. student
  2. freelancer
  3. sole_proprietorship
  4. partnership
  5. limited_company
business_namestringtrueName of businesss
business_payment_typestringtruePrimary mode through which the business receives revenue. Possible values:
  1. mpesa
  2. bank
  3. cash
business_locationstringtrueCity and Country of where business operates in
gross_monthly_revenueintegertrueMonthly revenue the business generates
average_monthly_expensesintegertrueAverage monthly expenses
average_monthly_personal_expenseintegertrueThe customer's monthly expenses
business_industrystringtrueIndustry in which the customer business operates in. Possible values:
  1. Accounting Auditing & Finance
  2. Administrative & Office
  3. Agriculture &Farming
  4. Building & Architecture
  5. Community & Social Services
  6. Consulting and Strategy
  7. Creative & Design
  8. Customer service & Support
  9. Employability & Soft Skills
  10. Engineering
  11. Food sciences & catering
  12. Health & Safety
  13. Hospitality/Leisure & Travel
  14. Human Resources
  15. IT & Software
  16. Legal Services
  17. Management & Business Development
  18. Marketing & Communication
  19. Medical & Pharmaceutical
  20. Natural sciences
  21. Project & Product management
  22. Quality Control & Assurance
  23. Real estate & Property Management
  24. Research/Teaching/Training
  25. Sales
  26. Security
  27. Supply Chain & Development
  28. Trade & Services
  29. Transport & Logistics
  30. Other
business_registeredbooleantrueWhether or not the business is registered

Create credit limit

POST /api/v2/limits

curl request

curl -i -X POST 'https://core-v2-multi-country.herokuapp.com/api/v2/limits' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "Test",
"last_name": "User",
"id_number": "550000055",
"country_code": "ke",
"phone_number": "+254726325093",
"employed": "true",
"gender": "male",
"date_of_birth": "21/12/1980",
"marital_status": "single",
"email": "donovan16@langworth1.com",
"password": "password",
"loan_amount": "5000",
"referral_source": "store_cbd",
"employed_occupational_detail": {
"employer": "Marius",
"net_income": "300000",
"expenses": "50000",
"job_function": "Intern",
"job_level": "Accounting Auditing & Finance",
"employer_sector": "private_sector",
"job_group": "M",
"payment_type": "bank"
}
}'

Employed (Private sector) JSON request object

{
"first_name": "Test",
"last_name": "User",
"id_number": "550000055",
"country_code": "ke",
"phone_number": "+254726325093",
"employed": "true",
"gender": "male",
"date_of_birth": "21/12/1980",
"marital_status": "single",
"email": "donovan16@langworth1.com",
"password": "password",
"loan_amount": "5000",
"referral_source": "store_cbd",
"employed_occupational_detail": {
"employer": "Marius",
"net_income": "300000",
"expenses": "50000",
"job_function": "Intern",
"job_level": "Accounting Auditing & Finance",
"employer_sector": "private_sector",
"payment_type": "bank"
}
}

Employed (Government) JSON Request Object

tip

For government employees the payload is similar to private sector employees, set employer_sector to government_sector , add the job_group property: range between A-T and the employer property should contain the Ministry the customer works for.

Self-Employed JSON Request Object

{
"first_name": "Test",
"last_name": "User",
"id_number": "550000055",
"country_code": "ke",
"phone_number": "+254726325093",
"employed": "false",
"gender": "male",
"date_of_birth": "21/12/1980",
"marital_status": "single",
"email": "donovan16@langworth1.com",
"password": "password",
"loan_amount": "5000",
"referral_source": "store_cbd",
"self_employed_occupational_detail": {
"business_type": "freelancer",
"business_name": "MyBusiness",
"business_location": "Daykio Plaza",
"business_payment_type": "mobile_money",
"gross_monthly_revenue": "70000",
"average_monthly_expenses": "30000",
"average_monthly_personal_expense": "10000",
"business_registered": "true",
"business_industry": "Graphic Design"
}
}

JSON Response

{
"request_id": "be2429d7-f74e-4b89-b9b6-0b4555f217a3",
"apiVersion": "2.0",
"status": 201,
"data": {
"updated": "2020-11-24T14:54:49.539Z",
"customer_details": {
"id": "d3462ed8-b5c7-4fab-aae9-9c18002f66d5",
"first_name": "Test",
"last_name": "User",
"email": "donovan16@langworth1.com",
"id_number": "550000055",
"mobile_number": "+254726325093",
"referral_source": "Partner Intergration"
},
"credit_limit_details": {
"id": "b5dfc583-c064-4241-8aea-79aa59248925",
"credit_limit": 347000,
"available_limit": 347000,
"credit_limit_status": "limit_active"
},
"payment_terms": {
"principal_amount": "75000.00",
"upfront_fees": "3750.00",
"first_installment": "10000.00",
"minimum_payment": "6250.00"
}
}
}

Fetch credit limit

GET /api/v2/limits/:customer_id

curl request

curl -i GET 'https://core-v2-multi-country.herokuapp.com/api/v2/limits/b7dd0bce-1c25-45ee-a458-6c5a765fb0f1'\
-H 'Authorization: Bearer <access_token>'
-H 'Content-Type: application/json'

JSON response

{
"request_id": "9f42ddc4-cf73-4866-83e6-6c9f8931f0fe",
"apiVersion": "2.0",
"status": 200,
"data": {
"updated": "2020-11-25T07:11:56.501Z",
"customer_details": {
"id": "b7dd0bce-1c25-45ee-a458-6c5a765fb0f1",
"first_name": "Test",
"last_name": "User",
"email": "n23@gmail.com",
"id_number": "31394165",
"mobile_number": "+254726325093",
"referral_source": "Partner Intergration"
},
"credit_limit_details": {
"id": "935a42ea-d4e2-4557-871a-4954049558c7",
"credit_limit": 500000.0,
"available_limit": 500000.0,
"credit_limit_status": "limit_active"
},
"payment_terms": {
"principal_amount": "75000.00",
"upfront_fees": "3750.00",
"first_installment": "10000.00",
"minimum_payment": "6250.00"
}
}
}