CrediCare API Documentation

Base URL: {APP_URL}/api

Authentication is handled by Laravel Sanctum. After login or register, the API returns a token; send it on authenticated requests with the header: Authorization: Bearer <token>

Health

GET /api/health

Check API availability.

Response: 200 OK

{
  "status": "ok",
  "timestamp": "2025-01-01T12:00:00.000000Z"
}

Authentication

POST /api/auth/login

Login and receive a Sanctum API token.

Body:

Field Type Required Description
email string Yes User email
password string Yes User password
role string No super-admin, regional-center, end-user

Response: 200 OK

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "fullName": "John Doe",
    "role": "end-user",
    "status": "active",
    "regionalCenterId": null,
    "regionalCenterName": null
  }
}

Errors: 401 Invalid email or password / Invalid role selected

POST /api/auth/register

Register a new end-user.

Body:

Field Type Required Description
fullName string Yes Full name
email string Yes Email
phone string No Phone
password string Yes Min 6 chars
panCard string No PAN number
aadhaar string No Aadhaar number

Response: 201 Created

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "fullName": "John Doe",
    "role": "end-user",
    "status": "pending_kyc"
  }
}

Errors: 400 Email already registered

POST /api/auth/forgot-password

Request a password reset link.

Body: { "email": "user@example.com" }

Response: 200 OK

{
  "message": "If an account exists for this email, you will receive a reset link."
}

POST /api/auth/reset-password

Reset password using token from email.

Body:

Field Type Required Description
token string Yes Reset token
password string Yes New password (min 6)

Response: 200 OK — { "message": "Password has been reset successfully" }

Errors: 400 Invalid or expired reset link / Link already used

Me (current user)

GET /api/me

Auth: Required

Returns the currently authenticated user.

Response: 200 OK

{
  "id": 1,
  "email": "user@example.com",
  "fullName": "John Doe",
  "role": "end-user",
  "status": "active",
  "regionalCenterId": null,
  "regionalCenterName": null
}

Contact (public)

POST /api/contact

Submit contact form.

Body:

Field Type Required
name string Yes
email string Yes
phone string Yes
subject string Yes
message string Yes

Response: 201 Created — { "message": "Message sent successfully. We'll get back to you within 24 hours." }

Partner (public)

POST /api/partner

Submit partner application.

Body:

Field Type Required
name string Yes
email string Yes
phone string Yes
city string Yes
state string Yes
message string Yes
company string No
experience string No
investment string No

Response: 201 Created — { "message": "Application submitted successfully. Our partnership team will contact you within 48 hours." }

Site settings

GET /api/site-settings

Auth: None (public)

Returns key-value site settings (logo, hero images, etc.).

Response: 200 OK

{
  "logo": "https://...",
  "logoAlt": "CrediCare",
  "heroHome": "https://...",
  "benefitsHome": "",
  "heroAbout": "",
  "heroProducts0": "",
  "heroProducts1": "",
  "heroServices": "",
  "heroPortfolio": "",
  "heroPartner": ""
}

PUT /api/site-settings

Auth: Required (super-admin)

Update site settings. Send only keys to update.

Body: { "logo": "https://...", "logoAlt": "CrediCare" }

Response: 200 OK — { "message": "Site settings updated" }

Fees

GET /api/fees/display

Auth: None (public)

Returns display-only fee percentages for bill payment and EMI conversion.

Response: 200 OK

{
  "creditCardPayment": 2.5,
  "emiConversion": 3.5
}

GET /api/fees

Auth: Required (super-admin)

Returns full fee configuration.

Response: 200 OK

{
  "creditCardPayment": 2.5,
  "emiConversion": 3.5,
  "rotationFee": 2.0,
  "lateFee": 5.0,
  "regionalShare": {
    "paymentProcessing": 40,
    "emiProcessing": 35,
    "onboarding": 50
  },
  "dynamicPricing": true
}

PUT /api/fees

Auth: Required (super-admin)

Update fee settings. All fields optional.

Body: Same shape as GET response (partial allowed).

Response: 200 OK — { "message": "Fee settings updated" }

Users (super-admin)

GET /api/users

Auth: Required (super-admin)

Query: search (optional) — filter by name or email

Response: 200 OK — Array of:

{
  "id": 1,
  "name": "John Doe",
  "email": "user@example.com",
  "role": "End User",
  "status": "Active",
  "joined": "2025-01-01",
  "transactions": 10
}

POST /api/users

Auth: Required (super-admin)

Body:

Field Type Required Description
fullName string Yes Full name
email string Yes Email (unique)
phone string No Phone
password string Yes Min 6 chars
role string Yes end-user, regional-center, super-admin
regionalCenterId number No Required if role is regional-center

Response: 201 Created — { "message": "User created" }

PATCH /api/users/{id}/status

Auth: Required (super-admin)

Body: { "status": "active" } or { "status": "suspended" }

Response: 200 OK — { "message": "Status updated" }

GET /api/users/stats

Auth: Required (super-admin)

Response: 200 OK

{
  "totalUsers": 100,
  "regionalCenters": 5,
  "pendingKyc": 12
}

Credit cards (end-user)

GET /api/credit-cards

Auth: Required (end-user)

Response: 200 OK — Array of:

{
  "id": "1",
  "bank": "HDFC Bank",
  "last4": "4529",
  "outstanding": 45200,
  "dueDate": "Oct 30, 2024",
  "color": "from-blue-600 to-blue-700"
}

POST /api/credit-cards

Auth: Required (end-user)

Body:

Field Type Required
bankName string Yes
lastFour string Yes (4 digits)
outstandingAmount number Yes (≥ 0)
dueDate string Yes (date)
color string No

Response: 201 Created — { "message": "Card added" }

PATCH /api/credit-cards/{id}

Auth: Required (end-user)

Body: { "outstandingAmount": 30000 } and/or { "dueDate": "2024-11-15" }

Response: 200 OK — { "message": "Card updated" }

Payments (end-user)

POST /api/payments/bill

Auth: Required (end-user)

Body:

Field Type Required
creditCardId integer Yes
amount number Yes (≥ 100)
paymentMethod string Yes (upi, debit, netbanking)
rotationEnabled boolean No
splitParts integer No (2–6)

Response: 201 Created

{
  "transactionId": "TXN1735123456",
  "amount": 10000,
  "fee": 250,
  "total": 10250,
  "status": "completed"
}

POST /api/payments/emi

Auth: Required (end-user)

Body:

Field Type Required
creditCardId integer Yes
amount number Yes (≥ 1000)
tenure integer Yes (3–24 months)
interestRate number Yes (≥ 0)

Response: 201 Created

{
  "emiPlanId": 1,
  "monthlyEmi": 8500.5,
  "totalPayable": 102006,
  "tenure": 12
}

Transactions

GET /api/transactions

Auth: Required (role-based scope: end-user sees own, regional-center sees center’s, super-admin sees all)

Query: status (optional), type (optional), search (optional)

Response: 200 OK — Array of:

{
  "id": "TXN001",
  "customer": "John Doe",
  "amount": 25000,
  "fee": 625,
  "commission": 250,
  "method": "upi",
  "status": "completed",
  "date": "2025-01-01T12:00:00.000000Z",
  "type": "bill_payment"
}

GET /api/transactions/recent

Auth: Required (super-admin or regional-center)

Response: 200 OK — Array of:

{
  "user": "John Doe",
  "amount": "₹25,000",
  "status": "completed",
  "time": "2025-01-01T12:00:00.000000Z"
}

GET /api/transactions/analytics

Auth: Required

Query: period (optional) — 7d, 30d, 6m (default)

Response: 200 OK

{
  "totalRevenue": 500000,
  "totalTransactions": 120,
  "activeUsers": 45,
  "avgTransaction": "4166",
  "transactionTrend": [
    { "month": "Jan", "transactions": 40, "revenue": 166640 }
  ],
  "paymentMethodData": [
    { "name": "upi", "value": 60, "color": "#3B82F6" }
  ]
}

Dashboard

GET /api/dashboard/analytics

Auth: Required

Query: period (optional) — 7d, 30d, 6m

Same response shape as GET /api/transactions/analytics. Scoped by user role (end-user, regional-center, super-admin).

EMI plans (end-user)

GET /api/emi/plans

Auth: Required (end-user)

Response: 200 OK — Array of:

{
  "id": 1,
  "description": "HDFC Bank ****4529",
  "principal": 100000,
  "interestRate": 12,
  "tenure": 12,
  "monthlyEmi": 8885,
  "progress": "3/12",
  "remaining": 79965
}

Payment gateways (super-admin)

GET /api/payment-gateways

Auth: Required (super-admin)

Response: 200 OK

{
  "gateways": [
    {
      "id": 1,
      "name": "Razorpay",
      "slug": "razorpay",
      "isActive": true,
      "config": null
    }
  ],
  "summary": {
    "activeGateways": 2,
    "totalProcessedToday": 150000,
    "todayTransactions": 8,
    "successRate": 95.5
  }
}

PATCH /api/payment-gateways/{id}

Auth: Required (super-admin)

Body: { "isActive": false }, apiKey, apiSecret, merchantId (all optional)

Response: 200 OK — { "message": "Gateway updated" }

Regional centers (super-admin)

GET /api/regional-centers

Auth: Required (super-admin)

Response: 200 OK — Array of:

{
  "id": 1,
  "name": "Mumbai Payment Center",
  "email": "mumbai@rpc.com",
  "phone": "+91 98765 43210",
  "userCount": 25
}

Notifications

GET /api/notifications

Auth: Required

Response: 200 OK — Array of:

{
  "id": 1,
  "title": "Payment Due Soon",
  "message": "HDFC Card payment due on Oct 30",
  "type": "reminder",
  "isRead": false,
  "createdAt": "2025-01-01T12:00:00.000000Z"
}

PATCH /api/notifications/{id}/read

Auth: Required

Response: 200 OK — { "message": "Marked as read" }

GET /api/notifications/unread-count

Auth: Required

Response: 200 OK — { "count": 3 }

KYC

POST /api/kyc/submit

Auth: Required (end-user)

Body: panCard, aadhaar (optional strings). Optional files: panCardFile, aadhaarFile, addressProofFile.

Response: 200 OK — { "message": "KYC submitted for review" }

GET /api/kyc/pending

Auth: Required (regional-center)

Response: 200 OK — Array of pending customer applications.

GET /api/kyc/approved

Auth: Required (regional-center)

Response: 200 OK — Array of approved customers for the center.

POST /api/kyc/{userId}/review

Auth: Required (regional-center)

Body: { "action": "approve" } or { "action": "reject", "reason": "..." }

Response: 200 OK — { "message": "Customer approved" } or { "message": "Application rejected" }

POST /api/kyc/onboard

Auth: Required (regional-center)

Body: fullName, email (required), phone, panCard, aadhaar (optional)

Response: 201 Created — { "message": "Customer added for KYC review", "userId": 1 }

Error responses

  • 400 — Validation or business error: { "error": "Message" } or { "errors": { "field": ["..."] } }
  • 401 — Missing or invalid token: { "error": "Authentication required" } or { "error": "Invalid or expired token" }
  • 403 — Forbidden: { "error": "Insufficient permissions" }
  • 404 — Not found: { "error": "Card not found" }
  • 500 — Server error: { "error": "Server error" }