# User (Jobseeker) Packages – API Reference

Base URL: `https://your-domain.com/api`  
All package endpoints require **Bearer token** (auth:api).

---

## 1. Get all packages + my status

**GET** `/api/user/packages`

Returns featured package (if any), job-apply packages, and current user status (featured active, job package, quota).

**Response (200):**
```json
{
  "success": true,
  "message": "Packages retrieved successfully",
  "data": {
    "featured_package": {
      "id": 9,
      "package_title": "Featured Profile",
      "package_price": 29.99,
      "package_num_days": 30,
      "currency": "USD",
      "package_for": "featured",
      "is_purchased": false,
      "expires_at": null
    },
    "job_apply_packages": [
      {
        "id": 1,
        "package_title": "Basic",
        "package_price": 0,
        "package_num_days": 30,
        "package_num_listings": 5,
        "currency": "USD",
        "package_for": "job_apply",
        "is_current": true,
        "package_end_date": "2026-03-15 00:00:00",
        "jobs_quota": 5,
        "availed_jobs_quota": 2
      }
    ],
    "my_status": {
      "is_featured": false,
      "featured_expires_at": null,
      "current_job_package_id": 1,
      "job_package_expires_at": "2026-03-15 00:00:00",
      "jobs_quota": 5,
      "availed_jobs_quota": 2
    }
  }
}
```

---

## 2. Get featured package only

**GET** `/api/user/packages/featured`

Returns the single **featured profile** package and whether the user has it active.

**Response (200):**
```json
{
  "success": true,
  "message": "Featured package retrieved",
  "data": {
    "id": 9,
    "package_title": "Featured Profile",
    "package_price": 29.99,
    "package_num_days": 30,
    "currency": "USD",
    "is_purchased": false,
    "expires_at": null
  }
}
```

---

## 3. Get job-apply packages only

**GET** `/api/user/packages/job-apply`

Returns all **job apply** packages (multiple) with user’s current package and quota.

**Response (200):**
```json
{
  "success": true,
  "message": "Job apply packages retrieved",
  "data": [
    {
      "id": 1,
      "package_title": "Basic",
      "package_price": 0,
      "package_num_days": 30,
      "package_num_listings": 5,
      "currency": "USD",
      "is_current": true,
      "package_end_date": "2026-03-15 00:00:00",
      "jobs_quota": 5,
      "availed_jobs_quota": 2
    }
  ]
}
```

---

## 4. Get my package status

**GET** `/api/user/package-status`

Returns current user’s package status: featured, job package expiry, quota, remaining applications, and whether they can apply.

**Response (200):**
```json
{
  "success": true,
  "message": "Package status retrieved",
  "data": {
    "is_featured": false,
    "featured_expires_at": null,
    "featured_expired": true,
    "current_package_id": 1,
    "current_package_title": "Basic",
    "package_expires_at": "2026-03-15 00:00:00",
    "job_package_expired": false,
    "jobs_quota": 5,
    "availed_jobs_quota": 2,
    "remaining_applications": 3,
    "can_apply": true
  }
}
```

---

## 5. Get single package detail (for payment)

**GET** `/api/user/package/{id}`

Returns one package by id and available payment gateways (for paid packages). Use before showing “Buy” or payment options.

**Response (200):**
```json
{
  "success": true,
  "message": "Package detail retrieved",
  "data": {
    "id": 9,
    "package_title": "Featured Profile",
    "package_price": 29.99,
    "package_num_days": 30,
    "package_num_listings": 0,
    "package_for": "make_featured",
    "currency": "USD",
    "is_free": false,
    "payment_gateways": [
      { "key": "paypal", "name": "Pay with PayPal" },
      { "key": "stripe", "name": "Pay with Stripe" }
    ]
  }
}
```

---

## 6. Order free package

**GET** `/api/user/order-free-package/{id}`

Activates a **free** package for the current user (featured or job-seeker). Only for packages with `package_price = 0`.

**Response (200):**
```json
{
  "success": true,
  "message": "Free package activated successfully",
  "data": {
    "package_id": 1,
    "package_title": "Basic",
    "package_num_days": 30,
    "package_num_listings": 5,
    "package_end_date": "2026-03-15 00:00:00",
    "jobs_quota": 5
  }
}
```

**Response (400)** – not free or not for job seeker:
```json
{
  "success": false,
  "message": "This is not a free package"
}
```

---

## Summary – API URLs for app integration

| Purpose                    | Method | URL |
|---------------------------|--------|-----|
| All packages + my status  | GET    | `/api/user/packages` |
| Featured package only    | GET    | `/api/user/packages/featured` |
| Job-apply packages only  | GET    | `/api/user/packages/job-apply` |
| My package status        | GET    | `/api/user/package-status` |
| Single package + gateways| GET    | `/api/user/package/{id}` |
| Activate free package    | GET    | `/api/user/order-free-package/{id}` |

---

## 7. Get active payment gateways

**GET** `/api/user/payment-gateways`  
**Auth:** Bearer required.

Returns which gateways are active and configured (PayPal, Stripe, Razorpay, etc.) and Stripe publishable key when Stripe is active.

**Response (200):**
```json
{
  "success": true,
  "message": "Payment gateways retrieved",
  "data": {
    "gateways": [
      { "key": "paypal", "name": "Pay with PayPal", "publishable_key": null },
      { "key": "stripe", "name": "Pay with Stripe", "publishable_key": "pk_live_xxx" }
    ],
    "currency": "USD"
  }
}
```

---

## 8. Initiate PayPal payment (paid package)

**POST** `/api/user/initiate-paypal-payment`  
**Auth:** Bearer required.  
**Body:** `{ "package_id": 9 }`

Creates a PayPal payment and returns `approval_url`. App should open this URL in a browser/WebView. After the user pays, PayPal redirects to `/api/user/paypal-execute?...` and the backend activates the package.

**Response (200):**
```json
{
  "success": true,
  "message": "Open the URL in browser/WebView to complete payment",
  "data": {
    "approval_url": "https://www.sandbox.paypal.com/checkoutnow?token=...",
    "payment_id": "PAYID-..."
  }
}
```

---

## 9. PayPal execute (callback – no auth)

**GET** `/api/user/paypal-execute?paymentId=...&PayerID=...&token=...`

Called by PayPal when the user is redirected back after payment. Do not call from the app with Bearer; the backend identifies the user from the stored pending payment. Returns JSON success/failure.

---

## 10. Process Stripe payment (paid package)

**POST** `/api/user/stripe-order-package`  
**Auth:** Bearer required.  
**Body:** `{ "package_id": 9, "stripe_token": "tok_xxx" }`

`stripe_token` is obtained from Stripe.js or the Stripe SDK on the client (using the publishable key from `payment-gateways`). Backend charges the card and, on success, activates the package.

**Response (200):**
```json
{
  "success": true,
  "message": "Payment successful. Package activated.",
  "data": {
    "package_id": 9,
    "package_title": "Featured Profile",
    "transaction_id": "ch_..."
  }
}
```

---

## 11. Razorpay – initiate order

**POST** `/api/user/initiate-razorpay-order`  
**Auth:** Bearer required.  
**Body:** `{ "package_id": 9 }`

Returns `order_id`, `amount`, `currency`, and `key`. Use these with the Razorpay SDK to show checkout. After payment, call verify with `razorpay_order_id`, `razorpay_payment_id`, `razorpay_signature`.

---

## 12. Razorpay – verify payment

**POST** `/api/user/verify-razorpay-payment`  
**Auth:** Bearer required.  
**Body:** `{ "razorpay_order_id": "...", "razorpay_payment_id": "...", "razorpay_signature": "..." }`

Verifies the payment and activates the package.

---

## 13. Paystack – initiate payment

**POST** `/api/user/initiate-paystack-payment`  
**Auth:** Bearer required.  
**Body:** `{ "package_id": 9 }`

Returns `authorization_url`. Open this URL in a browser/WebView. After payment, Paystack redirects to `/api/user/paystack-callback` (no auth).

---

## 14. Iyzico – initiate payment

**POST** `/api/user/initiate-iyzico-payment`  
**Auth:** Bearer required.  
**Body:** `{ "package_id": 9 }`

Returns `payment_page_url`. Open this URL in a browser/WebView. After payment, Iyzico redirects to `/api/user/iyzico-callback` (no auth).

---

## Summary – API URLs for app integration

| Purpose                    | Method | URL |
|---------------------------|--------|-----|
| All packages + my status  | GET    | `/api/user/packages` |
| Featured package only    | GET    | `/api/user/packages/featured` |
| Job-apply packages only  | GET    | `/api/user/packages/job-apply` |
| My package status        | GET    | `/api/user/package-status` |
| Single package + gateways| GET    | `/api/user/package/{id}` |
| Activate free package    | GET    | `/api/user/order-free-package/{id}` |
| **Active payment gateways** | GET  | `/api/user/payment-gateways` |
| **Initiate PayPal**       | POST   | `/api/user/initiate-paypal-payment` |
| **PayPal callback**       | GET    | `/api/user/paypal-execute` (no auth) |
| **Stripe payment**        | POST   | `/api/user/stripe-order-package` |
| **Initiate Razorpay**     | POST   | `/api/user/initiate-razorpay-order` |
| **Verify Razorpay**       | POST   | `/api/user/verify-razorpay-payment` |
| **Initiate Paystack**     | POST   | `/api/user/initiate-paystack-payment` |
| **Paystack callback**     | GET    | `/api/user/paystack-callback` (no auth) |
| **Initiate Iyzico**       | POST   | `/api/user/initiate-iyzico-payment` |
| **Iyzico callback**       | GET    | `/api/user/iyzico-callback` (no auth) |

**Implemented gateways:** PayPal, Stripe, Razorpay, Paystack, Iyzico.  
**Auth:** Send `Authorization: Bearer {access_token}` on all requests except the callback URLs.

---

## Payment History APIs (Candidate/Jobseeker)

Mirrors the candidate payment history page at `/candidate-payment-history`.

| Purpose | Method | URL |
|---------|--------|-----|
| Payment history list | GET | `/api/payment-history` or `/api/user/payment-history` |
| Payment statistics | GET | `/api/payment-history/stats` or `/api/user/payment-history/stats` |
| Single payment detail | GET | `/api/payment-history/order/{id}` or `/api/user/payment-history/order/{id}` |
| Recent transactions | GET | `/api/payment-history/recent` |
| Payment methods used | GET | `/api/payment-history/methods` |

**Query params for list:** `package_type`, `payment_method`, `date_from`, `date_to`, `per_page`  
**Response:** Uses `payment_history` table (package_title, package_price, payment_method, package_start_date, package_end_date, jobs_quota, payment_status, etc.)