Developer Portal
Abhi Open API
Introduction
Abhi offers a set of APIs to 3rd parties for the purpose of integration to render EWA services to the external platform.
3rd parties system shall integrate Abhi API(s) in its platform to offer the frontend application to its end users. The users will essentially log in to the 3rd party system & the 3rd party system in turn will call Abhi API(s) to render its services.
As part of the one-time onboarding, Abhi team set up the root organization for 3rd parties. This will allow the 3rd party system to create employees under the root organization. Moreover, additional organizations can be created under the root organizations, allowing 3rd party system to create employees under each orgnaization seperately. Users or employees of one organization can not access detail of other organization, however admin shall be able to access all child organizaiton details.
Authentication
Upon successful login, Abhi authenciation system shall generate a JWT token with 24 hours validity. All subsequent API calls must include the provided JWT token in the header to prove the identity and Abhi shall provide the relevant data in response to the APIs.
NOTES:
- By default, multi login is not allowed, therefore in case if a user is already logged in with a valid JWT token, the next successful attempt will invalid earlier token.
- Five consective wrong attempts will lock the user login.
Employee
API reference for Employee endpoints
GETGet All Employees
This is a sample HTTP request along with the response from the API. This request is for the GET method on the endpoint /connect/employees, with query parameters page=1 and limit=10. The response returned by the API contains information about a single employee, including
- ID: This is a UUID.
- Creation date
- Joining date
- Salary, and personal information like name, CNIC, date of birth, etc.
The response also includes some metadata like the total number of results and the status of the request (status, code, and message).
curl --location 'https://sandbox.abhi.com.pk/uat-open-api/employees?page=1&limit=10'{
"data": {
"total": 1,
"results": [
{
"id": "39e542ee-ae52-4a57-af31-d97b4b02178c",
"createdAt": "2023-03-08T11:46:03.196Z",
"deletedDate": null,
"employeeCode": null,
"dateOfJoining": "2023-03-06T00:00:00.000Z",
"organizationId": "df35ced3-42a8-4e29-9f03-998772892dff",
"netSalary": "500000",
"updatedAt": "2023-03-08T11:51:37.339Z",
"person": {
"firstName": "John",
"lastName": "Doe",
"cnic": "4210187123176",
"dob": "1970-01-01",
"user": {
"enabled": true,
"username": "john.doe@gmail.com"
}
},
"selectedBankAccount": {
"accountTitle": "John Doe",
"accountNumber": "1231221312312",
"bank": {
"bankName": "Silk Bank"
}
},
"officialEmail": {
"email": "john.doe@gmail.com"
},
"organization": {
"name": "Acme"
},
"limit": 50
}
]
},
"message": "Success",
"status": "success",
"code": 200
}POSTAdd Employee
This is a sample HTTP request to add an employee. The request contains a JSON payload with information about a single employee.
The payload includes the following information for the employee:
- employeeCode: Optional - It can be alpha numeric
- firstName: Mandatory: Maximum 32 characters limit allowed
- lastName: Mandatory: xxxxxxxxxxxxxxxxxxxx
- cnic: Mandatory: 13 digits CNIC without dashes, e.g. 3268617554925
- gender: Mandatory: Supported values include 'Male' , 'Female'
- department: Optional
- designation: Optional
- phone: Mandatory: +92XXXXXXXXXX format supported
- email: Mandatory
- dob: Optional
- dateOfJoining: Optional: The earned wage balance amount computation starts from the date of joining., therefore in case this field is not provided, the current system date is taken as date of joinging.
- netSalary: Mandatory: Number should be postive above 0.
- accountNumber: Mandatory: This is the bank account number
- accountTitle: Mandatory: This is the bank account title
- bankId: Mandatory. The list of bank can be obained via
/connect/mics/banksAPI shown below
In this example the API has successfully processed the request, as the response includes a "status" field with the value "success" and a "code" field with the value 200. The response also includes a "message" field with the value "Success".
{
"employees": [
{
"employeeCode": "",
"firstName": "John",
"lastName": "Doe",
"department": "tech",
"designation": "software engineer",
"phone": "",
"email": "john.doe@gmail.com",
"dob": "1970-01-01",
"dateOfJoining": "2023-03-06",
"accountTitle": "John Doe",
"accountNumber": "1231871512312",
"netSalary": "500000",
"cnic": "4210187121564",
"gender": "Male",
"bankId": "1694afcf-832a-4837-993f-42b426c8b1ee"
}
]
}curl --location 'https://sandbox.abhi.com.pk/uat-open-api/employees'
--data-raw '{
"employees": [
{
"employeeCode": "",
"firstName": "John",
"lastName": "Doe",
"department": "tech",
"designation": "software engineer",
"phone": "",
"email": "john.doe@gmail.com",
"dob": "1970-01-01",
"dateOfJoining": "2023-03-06",
"accountTitle": "John Doe",
"accountNumber": "1231871512312",
"netSalary": "500000",
"cnic": "4210187121564",
"gender": "Male",
"bankId": "1694afcf-832a-4837-993f-42b426c8b1ee"
}
]
}'{
"data": [],
"message": "Success",
"status": "success",
"code": 200
}PUTUpdate Employees
This is a sample HTTP request to update an employee. The request contains a JSON payload with an array of employees.
The payload includes the following information for the employee:
- id: Mandatory: The UUID of employee.
- employeeCode: Optional - It can be alpha numeric
- firstName: Mandatory: Maximum 32 characters limit allowed
- lastName: Mandatory: Maximum 32 characters limit allowed
- cnic: Mandatory: 13 digits CNIC without dashes, e.g. 3268617554925
- gender: Mandatory: Supported values include 'Male' , 'Female'
- department: Optional
- designation: Optional
- phone: Mandatory: +92XXXXXXXXXX format supported
- email: Mandatory
- dob: Optional
- dateOfJoining: Optional: The earned wage balance amount computation starts from the date of joining., therefore in case this field is not provided, the current system date is taken as date of joinging.
- netSalary: Mandatory: Number should be postive above 0.
- accountNumber: Mandatory: This is the bank account number
- accountTitle: Mandatory: This is the bank account title
- bankId: Mandatory: This can be obained via list of bank API shown below under Miscellaneous API refernces
/connect/mics/banks
{
"employees": [
{
"id": "39e542ee-ae52-4a57-af31-d97b4b02178c",
"employeeCode": "",
"firstName": "test 3",
"lastName": "processed_ok",
"department": "tech",
"designation": "software engineer",
"phone": "",
"email": "sheikh.hammd+user4@gmail.com",
"dob": "1970-01-01",
"dateOfJoining": "2023-03-06",
"accountTitle": "PROCESSED_OK",
"accountNumber": "1231221312312",
"netSalary": "500000",
"cnic": "4210187123176",
"gender": "Male",
"bankId": "1694afcf-832a-4837-993f-42b426c8b1ee"
}
]
}curl --location --request PUT 'https://sandbox.abhi.com.pk/uat-open-api/employees' \
--data-raw '{
"employees": [
{
"employeeCode": "",
"firstName": "John",
"lastName": "Doe",
"department": "tech",
"designation": "software engineer",
"phone": "",
"email": "john.doe@gmail.com",
"dob": "1970-01-01",
"dateOfJoining": "2023-03-06",
"accountTitle": "John Doe",
"accountNumber": "1231871512312",
"netSalary": "500000",
"cnic": "4210187121564",
"gender": "Male",
"bankId": "1694afcf-832a-4837-993f-42b426c8b1ee"
}
]
}'{
"data": {
"editStatus": "All employees are updated Successfully!"
},
"message": "Success",
"status": "success",
"code": 200
}DELETEDelete Employee
This is a HTTP request to delete employee records from the API. The payload includes a single field "cnicArray", which is an array of CNIC numbers for the employees to be deleted. In this case, the array contains a single CNIC number.
The response from the API indicates that the employees were deleted successfully. The response is also in JSON format and includes the following information:
- data: an object containing information about the status of the deletion
- message: a string indicating that the employees were deleted successfully
- status: a string indicating the status of the API call (in this case, "success")
- code: a numerical HTTP status code indicating the success of the API call (in this case, 200)
{
"cnicArray": ["4210187123175"]
}curl --location --request DELETE 'https://sandbox.abhi.com.pk/uat-open-api/employees' \
--data '{
"cnicArray": ["4210187121564"]
}'{
"data": {
"updated": true,
"cnicFailed": []
},
"message": "Employes Deleted Successfully",
"status": "success",
"code": 200
}
Transactions
API reference for Transactions endpoints
Employee
Transactions API endpoints for Employees
POST Post Transaction
This is a HTTP request to create a new transaction for an employee. The request is being sent to a URL path /connect/transactions/employee.
The payload of the request is in JSON format and contains information about the transaction ie. a single field "amount", which has a value of 500.
{
"amount": 500
}curl --location 'https://sandbox.abhi.com.pk/uat-open-api/transaction/employee/post-transaction' \
--data '{
"amount": 550
}'{
"data": {},
"message": "Your account details are not approved. Please contact your HR.",
"status": "bad request",
"code": 400
}POSTGet Employee Transaction History
This is a sample HTTP request to retrieve transaction history for an employee using the API endpoint /connect/transactions/employee/history. The request is a POST method and includes query parameters for pagination (limit and page). The request body includes a JSON payload with the amount to be transferred (amount).
The API response is also in JSON format and includes information about the transaction history, such as the total amount, transaction date, account details, and any error messages associated with the transaction. The response also includes a message and status indicating whether the request was successful or not.
curl --location --request POST 'https://sandbox.abhi.com.pk/uat-open-api/transaction/employee/history/?limit=10&page=1'{
"data": {
"totalAmount": 0,
"transactions": {
"08-03-2023": [
{
"id": "760ab263-2297-461c-8e22-940b5c7bdf5a",
"amount": "500",
"fee": "90",
"transactionStatus": "error",
"transactionDate": "2023-03-08T12:02:42.508Z",
"errorMessage": "GatewayCriticalError: from: titleFetch | STAN: 070684| ResponseDetail: PROCESSED OK",
"accountToNumber": "1231221312312",
"accountToTitle": "John Doe",
"accountToBank": "Silk Bank",
"stan": null,
"accountNumber": "1231221312312",
"accountName": "PROCESSED_OK"
}
]
}
},
"message": "Success",
"status": "success",
"code": 200
}GETGet Traansaction Status
This is a HTTP request to the API endpoint /connect/transactions/employee/status/760ab263-2297-461c-8e22-940b5c7bdf5a. The request includes a JSON payload with a `data` object containing an id field with the value "eefda895-30cb-479e-85bb-f64c1592b09c" and a status field with the value "error".
The response to the request has a status field with the value "success", a message field with the value "Success", and a `code` field with the value 200.
curl --location 'https://sandbox.abhi.com.pk/uat-open-api/status/760ab263-2297-461c-8e22-940b5c7bdf5a'{
"data": {
"id": "eefda895-30cb-479e-85bb-f64c1592b09c",
"status": "error"
},
"message": "Success",
"status": "success",
"code": 200
}GETGet Monthly Balance
This is a HTTP request to get monthly balance of employee. The request is asking for employee transaction and balance information, and the response contains data related to salary, available salary, available balance, total withdrawals, daily available salary, total days in the month, and a breakdown of the balance on each day of the month.
The breakdown of the balance includes information about the date, day of the month, the amount of money withdrawn on that day, the total amount of money withdrawn up to that day, and the remaining balance after each day.
The response will include
- salary: This is the net salary amount provided at the time of creating the employee (or edit at later stage)
- avilableSalary: This is the risk adjusted salary that act as the benchmark to compute the accessible balance. There, if a person has 100,000/- net salary, with 50% risk limit, the available salary will be 50.000/-
- availableBalance: This is the amount accessible by the specific user at the time of accessing the API. This is adjusted balance having all withdrawals deducted in current payroll cycle, allowing the user to draw down any amount up to avaialble Balance.
- totalWithdraw: This is the sum of all withdrawals by the specific user in current payroll cycle.
- perDayAvilableSalary: This is the prorated salary on day basis.
- totalDaysOfMonth: This specifies the total no. of days in current payroll cycle.
- monthlyBreakup: This provides an array of day by day withdrawals with running withrawal amount of the user in current payroll cycle, including
- date: This is the date starting from the first day of the payroll cycle
- day: This is the number of day in current payroll cycle
- withdrawMondy: This is the amount withdrawn on specific date
- totalWithdraw: This is the running withdraw balance.
- balane: This is the accessible balance at the specific date after adjusting the withdrawMony on the particular day.
curl --location 'https://sandbox.abhi.com.pk/uat-open-api/transaction/employee/balance'{
"data": {
"salary": 500000,
"availableSalary": 250000,
"availableBalance": 21895,
"totalWithdraw": 500,
"perDayAvailableSalary": 8064.5161290322585,
"totalDaysOfMonth": 31,
"monthlyBreakup": [
{
"date": "03-01-2023",
"day": 1,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 8065
},
{
"date": "03-02-2023",
"day": 2,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 16129
},
{
"date": "03-03-2023",
"day": 3,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 24194
},
{
"date": "03-04-2023",
"day": 4,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 32258
},
{
"date": "03-05-2023",
"day": 5,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 40323
},
{
"date": "03-06-2023",
"day": 6,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 48387
},
{
"date": "03-07-2023",
"day": 7,
"withdrawMoney": 0,
"totalWithdraw": 0,
"balance": 56452
},
{
"date": "03-08-2023",
"day": 8,
"withdrawMoney": 500,
"totalWithdraw": 500,
"balance": 64516
},
{
"date": "03-09-2023",
"day": 9,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 72581
},
{
"date": "03-10-2023",
"day": 10,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 80645
},
{
"date": "03-11-2023",
"day": 11,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 88710
},
{
"date": "03-12-2023",
"day": 12,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 96774
},
{
"date": "03-13-2023",
"day": 13,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 104839
},
{
"date": "03-14-2023",
"day": 14,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 112903
},
{
"date": "03-15-2023",
"day": 15,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 120968
},
{
"date": "03-16-2023",
"day": 16,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 129032
},
{
"date": "03-17-2023",
"day": 17,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 137097
},
{
"date": "03-18-2023",
"day": 18,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 145161
},
{
"date": "03-19-2023",
"day": 19,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 153226
},
{
"date": "03-20-2023",
"day": 20,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 161290
},
{
"date": "03-21-2023",
"day": 21,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 169355
},
{
"date": "03-22-2023",
"day": 22,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 177419
},
{
"date": "03-23-2023",
"day": 23,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 185484
},
{
"date": "03-24-2023",
"day": 24,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 193548
},
{
"date": "03-25-2023",
"day": 25,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 201613
},
{
"date": "03-26-2023",
"day": 26,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 209677
},
{
"date": "03-27-2023",
"day": 27,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 217742
},
{
"date": "03-28-2023",
"day": 28,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 225806
},
{
"date": "03-29-2023",
"day": 29,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 233871
},
{
"date": "03-30-2023",
"day": 30,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 241935
},
{
"date": "03-31-2023",
"day": 31,
"withdrawMoney": 0,
"totalWithdraw": 500,
"balance": 250000
}
]
},
"message": "success",
"status": "success",
"code": 200
}POSTValidate Transaction
This is a HTTP request to validate a transaction. This is to make sure if the transaction is processable, before creating a transaction request.
Upon processing the request, the server responds with a JSON object that includes a status, a code property and a message property.
The request is being used to validate a transaction involving an employee, with the amount of the transaction being specified in the request body. The response indicates either the transaction is processable or not based upon the status, code and message.
status: "success" , code: 200 and message : ""Transaction Is Processable"" indicates a processable transaction.
Any response other than success means the transaction is not processable with the reason stated in message field.
{
"amount": 500
}curl --location 'https://sandbox.abhi.com.pk/uat-open-api/transaction/employee/validate-transaction' \
--data '{
"amount": 500
}'{
"data": {},
"message": "Transaction Is Processable",
"status": "success",
"code": 200
}