Introduction

Overview

This document defines application endpoint specifications for integration with automated lending repayment system. It also defines data exchange between corporate pay and the lending repayment system.

SECURITY REQUIREMENT

The automated lending repayment system will utilizes OAuth2.0 and all Application endpoints are authenticated by default and therefore require that a service maintain a valid token for access to the resource server.

A raw json encoded text is sent in the body of a POST request to https://{base_url}/token to generate token while for token refresh, the url https://{base_url}/token/refresh is used.

AUTHORIZATION

Description: Authorise Application for Statistics service

Sample Request

Parameter	Type	Description	Required
username	string	Client application’s username	Yes
password	string	Client pin encrypted AES Encryption algorithm	Yes

POST /auth

curl `${base_url}/auth`
-H "Content-type: application/json"
-d '{
    "username": "app.username",
    "password" : "app.password"
}
-X POST

Sample Response

info

Standard OAuth2.0 parameters are returned in json format, in body of response. Below is a sample response:

Parameter	Type	Description	Mandatory
data	object	Response data block	Yes
access_token	string	Access token to be used when making calls to all APIs	Yes
expires_in	integer	Time in seconds for token expiration	Yes
refresh_expires_in	integer	Time in seconds for refresh token expiration	Yes
token_type	string	Token type	Yes
id_token	string	Ignore	No
not-before-policy	integer	Ignore	Yes
session_state	string	Ignore	Yes
scope	string	Ignore, not implemented	Yes
refreshToken	string	Hashed refresh token	Yes
status	integer	HTTP status code	Yes
message	string	Description of http status code	Yes
execTime	integer	Time taken to process request (for metrics and performance tracking)	Yes
error	string	Specific errors when request does not return a HTTP status of 200.	No

POST / auth

{
  "status": 200,
  "message": "successfully authenticated",
  "data": {
    "access_token": "hashed access token",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "token_type": "bearer",
    "id_token": null,
    "not-before-policy": 1635768787,
    "session_state": "",
    "scope": "",
    "refresh_token": "hashed access token"
  },
  "execTime": 1.4888868,
  "error": ""
}

REAUTHORIZATION

Description: Reauthorise Application for Statistics service

Sample Request

Parameter	Type	Description	Required
refresh_Token	string	Refresh token received during the initial token generation or last refresh.	Yes

POST /auth/refresh

curl `${base_url}/auth/refresh`
-H "Content-type: application/json"
-d '{
    "refreshToken": "token" 
}
-X POST

Sample Response

info

Standard OAuth2.0 parameters are returned in json format, in body of response. Below is a sample response:

Parameter	Type	Description	Mandatory
data	object	Response data block	Yes
access_token	string	Access token to be used when making calls to all APIs	Yes
expires_in	integer	Time in seconds for token expiration	Yes
refresh_expires_in	integer	Time in seconds for refresh token expiration	Yes
token_type	string	Token type	Yes
id_token	string	Ignore	No
not-before-policy	integer	Ignore	Yes
session_state	string	Ignore	Yes
scope	string	Ignore, not implemented	Yes
refreshToken	string	Hashed refresh token	Yes
status	integer	HTTP status code	Yes
message	string	Description of http status code	Yes
execTime	integer	Time taken to process request (for metrics and performance tracking)	Yes
error	string	Specific errors when request does not return a HTTP status of 200.	No

POST / auth/refresh

{
  "status": 200,
  "message": "successfully authenticated",
  "data": {
    "access_token": "hashed access token",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "token_type": "bearer",
    "id_token": null,
    "not-before-policy": 1635768787,
    "session_state": "",
    "scope": "",
    "refresh_token": "hashed access token"
  },
  "execTime": 1.4888868,
  "error": ""
}