EWA- Earned Waged Access
Overview
The EWA API provides a comprehensive solution for managing Employee Wage Access (EWA) operations. This API allows integration to check employee eligibility, calculate pricing, record consents, create salary advance applications, and manage the complete lifecycle of salary advance transactions.
Key Features
Eligibility Verification: Check if an employee is eligible for salary advance
Pricing Calculation: Get accurate pricing information including charges and taxes
Consent Management: Record and manage employee consent for EWA programs
Application Management: Create, retrieve, and cancel salary advance applications
Status Tracking: Monitor application status throughout the lifecycle
EWA Providers Supported
INNFINN
ABHI
Disbursement Types
REMITTANCE: Remittance transfer
Base URL
SBX : https://cdp-sbx.luluone.com
Production : https://cdp.luluone.com
Authentication API
An access token is the key to the gateway to access any other API. The API will return the access token if the user is successfully authenticated and has authorization to access these services. Every access token is tagged with validity, and the expiry duration is echoed in the response for the calling application to manage the state accordingly. A token that is used after its validity period will restrict access to any services, and a new token will be generated in this case.
API | https://{{baseUrl}}/auth/realms/cdp/protocol/openid-connect/token |
Method | POST |
Headers | Content-Type : application/x-www-form-urlencoded |
Request Payload | --data-urlencode 'grant_type=password' \
--data-urlencode 'scope=api://3a3f52a1-1b64-4c27-81f0-50a6ca01324d/customer' \
--data-urlencode 'client_id=<<client_id>>' \
--data-urlencode 'client_secret=<<secret>>' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<<username>>' \
--data-urlencode 'password=<<password>>' |
Response Payload Success Http Status : 200 Ok | {
"token_type": "bearer",
"access_token": "<<access_token_value>>",
"expires_in": 7199,
"refresh_expires_in": 7199,
"refresh_token": "<<refresh_token_value>>",
"scope": "----",
"not-before-policy": 0,
"session_state": "<<session_state>>"
} |
Response Payload Failure Http Status : 401 Unauthorized | {
"error": "invalid_grant",
"error_description": "Invalid user credentials"
} |
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | mandatory | Content type |
Payload
Field | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
grant_type | String | 10 | mandatory | Grant type. Will up provided |
scope | String | 60 | CONDITIONAL | Scope name. Will be provided |
client_id | String | 60 | mandatory | Client Id. Will be provided |
client_secret | String | 60 | mandatory | Client secret. Will be provided |
username | String | 60 | mandatory | Admin user name |
password | String | 60 | mandatory | Admin password |
Response
Field | Data Type | Max Length | Description |
|---|---|---|---|
token_type | String | - | Token type |
scope | String | - | Scope details |
access_token | String | 600 | Access token to access the APIs |
refresh_token | String | 600 | refresh token to refresh the Token. |
expires_in | Integer | - | Token expiry time in seconds |
refresh_expires_in | Integer | - | Refresh Token expiry time in seconds |
Check EWA Eligibility
Check if an employee is eligible for salary advance and get eligibility details including pricing information.
API | https://{{baseUrl}}/ewa/api/v1/salary/advance/eligibility |
Method | POST |
Headers | Content-Type : application/json Authorization : Bearer {JWT_TOKEN} |
Request Payload | {
"employeeEcrn": "7842420732744673",
"disbursementType": "REMITTANCE"
} |
Response Payload Eligible Customer Http Status : 200 Ok | {
"isEligible": true,
"pendingRecoveryAmount": 300.00,
"consentRequired": false,
"eligibleMinAmount": 100,
"eligibleMaxAmount": 2436,
"totalCharges": 121.8,
"totalTax": 6.09,
"currencyCode": "AED",
"ewaProvider": "ABHI",
"notEligibleTitle": null,
"notEligibleDetail": null
} |
Response Payload Eligible But Consent Required Http Status : 200 Ok | {
"isEligible": true,
"pendingRecoveryAmount": 0.0,
"consentRequired": true,
"eligibleMinAmount": 0.0,
"eligibleMaxAmount": 0.0,
"totalCharges": 0.0,
"totalTax": 0.0,
"currencyCode": "AED",
"ewaProvider": "ABHI",
"notEligibleTitle": null,
"notEligibleDetail": null
} |
Response Payload Not Eligible Http Status : 200 Ok | {
"isEligible": false,
"notEligibleTitle": "Employee salary is not yet processed",
"notEligibleDetail": "Employee 7842420732744673 with ECRN 7842420732744673 is not processed salary through LuLu UAE WPS yet",
"pendingRecoveryAmount": 0.0,
"consentRequired": false,
"eligibleMinAmount": 0.0,
"eligibleMaxAmount": 0.0,
"totalCharges": 0.0,
"totalTax": 0.0,
"currencyCode": "AED",
"ewaProvider": "ABHI"
} |
Response Payload Bad Request Http Status : 400 Bad Request | {
"type": "cdp-sbx.luluone.com/ewa/error/PF-GEN-0010",
"status": 400,
"code": "PF-GEN-0010",
"title": "Bad Request",
"detail": "",
"instance": "/api/v1/salary/advance/eligibility",
"traceId": "d1e670096e8f0e5d27e6f7c4d947343f",
"timestamp": "2025-11-03T18:12:16.220041326Z",
"invalidParameters": [
{
"name": "employeeEcrn",
"reason": "employeeEcrn should be alphanumeric"
}
]
} |
Response Payload Unauthorized Http Status : 401 Unauthorized | {
"type": "cdp-sbx.luluone.com/ewa/error/PF-GEN-0012",
"status": 401,
"code": "PF-GEN-0012",
"title": "Unauthorized",
"detail": "Missing Authorization token",
"instance": "/api/v1/salary/advance/eligibility",
"traceId": "c16efbe10ebf1dc730b04f54a94e6725",
"timestamp": "2025-11-03T18:11:46.399869822Z"
} |
If Consent Required:
When `consentRequired` is `true`, the employee must provide consent before creating a salary advance application. Use the Record Consent endpoint to record the consent.
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | mandatory | Content type |
Authorization | String |
| mandatory | Authorization Bearer Token |
Payload
Field | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
employeeEcrn | String | 50 | mandatory | Employee Customer Reference Number |
disbursementType | Enum |
| mandatory | Disbursement method type | Values: SALARY, REMITTANCE, CASH, BILL_PAYMENT |
Response
Field | Data Type | Max Length | Description |
|---|---|---|---|
isEligible | Boolean |
| Indicates if the employee is eligible for salary advance |
notEligibleTitle | String | 300 | Title of ineligibility reason (if not eligible) |
notEligibleDetail | String | 600 | Detailed explanation of ineligibility (if not eligible) |
pendingRecoveryAmount | BigDecimal |
| Amount pending recovery from previous advances |
consentRequired | Boolean |
| Indicates whether employee consent is required |
eligibleMinAmount | BigDecimal |
| Minimum eligible advance amount |
eligibleMaxAmount | BigDecimal |
| Maximum eligible advance amount |
totalCharges | BigDecimal |
| Total charges applicable for the advance |
totalTax | BigDecimal |
| Total tax applicable on charges |
currencyCode | String | 3 | Currency code |
ewaProvider | Enum |
| EWA provider |
Fetch Price
Get detailed pricing information for a specific salary advance amount.
API | https://{{baseUrl}}/ewa/api/v1/price/fetch |
Method | POST |
Headers | Content-Type : application/json Authorization : Bearer {JWT_TOKEN} |
Request Payload | {
"advanceSalary": "1000",
"agentLocationId": "784101",
"ewaProvider": "ABHI"
} |
Response Payload Success Http Status : 200 Ok | {
"totalCharges": 50.0,
"totalTax": 2.5,
"ewaProviderCharge": 30.0,
"luluCharge": 20.0,
"bankCharge": 0,
"riskFund": 0
} |
Response Payload Bad Request Http Status : 400 Bad Request | {
"type": "cdp-sbx.luluone.com/ewa/error/PF-GEN-0010",
"status": 400,
"code": "PF-GEN-0010",
"title": "Bad Request",
"detail": "",
"instance": "/api/v1/price/fetch",
"traceId": "41cabfdf55915dc5fc713f45cd928098",
"timestamp": "2025-11-03T18:09:39.519987018Z",
"invalidParameters": [
{
"name": "request",
"reason": "Invalid value for field 'ewaProvider'. Expected format: EWAProvider"
}
]
} |
Response Payload Unauthorized Http Status : 401 Unauthorized | {
"type": "about:blank",
"status": 401,
"code": "PF-GEN-0012",
"title": "Unauthorized",
"detail": "Missing Authorization token",
"instance": "/api/v1/price/fetch",
"traceId": "1c13fae91b3c8443422e36accb3b292e",
"timestamp": "2025-10-06T05:53:43.644122353Z"
} |
Header
Name | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
Content-Type | String | 36 | mandatory | Content type |
Authorization | String |
| mandatory | Authorization Bearer Token |
Payload
Field | Data Type | Max Length | Mandatory | Description |
|---|---|---|---|---|
advanceSalary | BigDecimal |
| mandatory | Salary advance amount | Must be >= 0 |
ewaProvider | Enum |
| mandatory | EWA provider | Values: INNFINN, ABHI |
Response
Field | Data Type | Max Length | Description |
|---|---|---|---|
totalCharges | BigDecimal |
| Total charges including all fees |
totalTax | BigDecimal |
| Total tax applicable |
ewaProviderCharge | BigDecimal |
| Charge from EWA provider |
luluCharge | BigDecimal |
| LuLu platform charge |
bankCharge | BigDecimal |
| Bank processing charge |
riskFund | BigDecimal |
| Risk fund contribution |
Record Consent
Record employee consent for EWA program participation.
API | https://{{baseUrl}}/ewa/api/v1/employee-ewa-program/record-consent |
Method | POST |
Headers | Content-Type : multipart/form-data Authorization : Bearer {JWT_TOKEN} |
Request Payload | {
"employeeEcrn": "7842420732744673",
"ewaProvider": "ABHI",
"disbursementType": "REMITTANCE",
"consentGiven": true
} |
Response Payload |