Installment Purchase - Public & Plan Endpoints

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-10-18
Version: v1.0

Base URL: https://api.nextgate.com/api/v1/installments

Short Description: This API provides public endpoints for browsing installment plans and calculating installment previews before checkout. These endpoints do not require authentication and are designed to help customers explore installment options, understand payment breakdowns, and make informed purchase decisions. The endpoints return detailed financial calculations including amortization schedules, interest breakdowns, and payment timelines.

Hints:

• Public endpoints do not require authentication
• Plans are filtered to show only active plans to customers
• Preview calculations use amortization formula for accurate payment schedules
• Early payoff discount (75% off remaining interest) is standard across all plans
• Down payment range: minimum set by plan (typically 10-20%), maximum 50% (platform limit)
• All financial calculations rounded to 2 decimal places
• Grace periods determine when first payment is due
• Fulfillment timing (IMMEDIATE vs AFTER_PAYMENT) affects when product ships
• APR (Annual Percentage Rate) converted to period rate based on payment frequency
• All amounts are in TZS (Tanzanian Shillings)

---

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-18T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
success	boolean	Always true for successful operations, false for errors
httpStatus	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message	string	Human-readable message describing the operation result
action_time	string	ISO 8601 timestamp of when the response was generated
data	object/string	Response payload for success, error details for failures

---

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

• GET - GET - Green (Safe, read-only operations)
• POST - POST - Blue (Create new resources)

---

Endpoints

1. Get Available Plans for Product

Purpose: Retrieve all active installment plans available for a specific product

Endpoint: GET {base_url}/products/{productId}/plans

Access Level: 🌐 Public (No Authentication Required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
productId	UUID	Yes	Unique identifier of the product	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Available installment plans retrieved successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": [
    {
      "planId": "4b5c6d7e-8f9a-4b1c-9d2e-3f4a5b6c7d8e",
      "planName": "Quick Payment Plan",
      "paymentFrequency": "WEEKLY",
      "paymentFrequencyDisplay": "Weekly",
      "customFrequencyDays": null,
      "numberOfPayments": 8,
      "duration": "8 weeks",
      "apr": 10.00,
      "minDownPaymentPercent": 20,
      "gracePeriodDays": 7,
      "fulfillmentTiming": "IMMEDIATE",
      "isActive": true,
      "isFeatured": false,
      "displayOrder": 1,
      "preview": {
        "productPrice": 2000000.00,
        "minDownPaymentAmount": 400000.00,
        "maxDownPaymentAmount": 1000000.00,
        "financedAmountExample": 1600000.00,
        "paymentAmountExample": 210000.00,
        "totalInterestExample": 80000.00,
        "totalCostExample": 2080000.00,
        "firstPaymentDateExample": "2025-10-25T00:00:00",
        "lastPaymentDateExample": "2025-12-13T00:00:00"
      }
    },
    {
      "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
      "planName": "Standard Monthly Plan",
      "paymentFrequency": "MONTHLY",
      "paymentFrequencyDisplay": "Monthly",
      "customFrequencyDays": null,
      "numberOfPayments": 12,
      "duration": "12 months",
      "apr": 15.00,
      "minDownPaymentPercent": 15,
      "gracePeriodDays": 30,
      "fulfillmentTiming": "IMMEDIATE",
      "isActive": true,
      "isFeatured": true,
      "displayOrder": 2,
      "preview": {
        "productPrice": 2000000.00,
        "minDownPaymentAmount": 300000.00,
        "maxDownPaymentAmount": 1000000.00,
        "financedAmountExample": 1700000.00,
        "paymentAmountExample": 156250.00,
        "totalInterestExample": 175000.00,
        "totalCostExample": 2175000.00,
        "firstPaymentDateExample": "2025-11-17T00:00:00",
        "lastPaymentDateExample": "2026-10-17T00:00:00"
      }
    },
    {
      "planId": "6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a",
      "planName": "Budget Friendly Plan",
      "paymentFrequency": "MONTHLY",
      "paymentFrequencyDisplay": "Monthly",
      "customFrequencyDays": null,
      "numberOfPayments": 24,
      "duration": "24 months",
      "apr": 18.00,
      "minDownPaymentPercent": 10,
      "gracePeriodDays": 30,
      "fulfillmentTiming": "AFTER_PAYMENT",
      "isActive": true,
      "isFeatured": false,
      "displayOrder": 3,
      "preview": {
        "productPrice": 2000000.00,
        "minDownPaymentAmount": 200000.00,
        "maxDownPaymentAmount": 1000000.00,
        "financedAmountExample": 1800000.00,
        "paymentAmountExample": 87500.00,
        "totalInterestExample": 300000.00,
        "totalCostExample": 2300000.00,
        "firstPaymentDateExample": "2025-11-17T00:00:00",
        "lastPaymentDateExample": "2027-10-17T00:00:00"
      }
    }
  ]
}

Success Response Fields:

Field	Description
planId	Unique identifier for the plan
planName	Display name of the plan
paymentFrequency	Payment frequency enum (DAILY, WEEKLY, BI_WEEKLY, SEMI_MONTHLY, MONTHLY, QUARTERLY, CUSTOM_DAYS)
paymentFrequencyDisplay	Human-readable payment frequency
customFrequencyDays	Custom frequency in days (only for CUSTOM_DAYS type)
numberOfPayments	Total number of payments in the plan
duration	Human-readable duration (e.g., "12 months", "8 weeks")
apr	Annual Percentage Rate
minDownPaymentPercent	Minimum down payment percentage required by this plan
gracePeriodDays	Days before first payment is due
fulfillmentTiming	When product ships (IMMEDIATE = after down payment, AFTER_PAYMENT = after final payment)
isActive	Whether plan is currently active
isFeatured	Whether plan is featured/recommended (shows "Most Popular" badge)
displayOrder	Order for display on product page
preview	Preview calculations object
preview.productPrice	Product price used for calculations
preview.minDownPaymentAmount	Minimum down payment amount
preview.maxDownPaymentAmount	Maximum down payment amount (platform limit: 50%)
preview.financedAmountExample	Amount being financed (at minimum down payment)
preview.paymentAmountExample	Each installment amount (at minimum down payment)
preview.totalInterestExample	Total interest to be paid (at minimum down payment)
preview.totalCostExample	Grand total cost including interest (at minimum down payment)
preview.firstPaymentDateExample	When first payment would be due
preview.lastPaymentDateExample	When last payment would be due

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found with ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "action_time": "2025-10-18T10:30:45",
  "data": "Product not found with ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Standard Error Types:

Application-Level Exceptions (400-499)

• 404 NOT_FOUND: Product not found or product does not have installment enabled

Error Response Examples:

Not Found - Product (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found with ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "action_time": "2025-10-18T10:30:45",
  "data": "Product not found with ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Special Cases:

• If product has installment disabled, returns empty array
• If product has no active plans, returns empty array
• Plans are automatically sorted by displayOrder

---

2. Calculate Installment Preview

Purpose: Calculate detailed payment breakdown and schedule for a specific plan with customer's chosen down payment percentage

Endpoint: POST {base_url}/calculate-preview

Access Level: 🌐 Public (No Authentication Required)

Authentication: None

Request Headers:

Header	Type	Required	Description
Content-Type	string	Yes	application/json

Request JSON Sample:

{
  "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "productPrice": 2000000.00,
  "quantity": 1,
  "downPaymentPercent": 20
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
planId	UUID	Yes	ID of the installment plan to calculate	Valid UUID format, plan must exist and be active
productPrice	decimal	Yes	Price of the product	Min: 0.01, Max: 999999999.99
quantity	integer	Yes	Quantity of product	Min: 1, Max: 1 (installment limited to 1 item)
downPaymentPercent	integer	Yes	Down payment percentage customer chooses	Min: 10, Max: 50, must be >= plan's minDownPaymentPercent

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Installment preview calculated successfully",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
    "planName": "Standard Monthly Plan",
    "planDescription": "Pay in 12 monthly installments at 15.0% APR",
    "paymentFrequency": "Monthly",
    "numberOfPayments": 12,
    "durationDisplay": "12 months",
    "apr": 15.00,
    "gracePeriodDays": 30,
    "productPrice": 2000000.00,
    "quantity": 1,
    "totalProductCost": 2000000.00,
    "downPaymentPercent": 20,
    "downPaymentAmount": 400000.00,
    "minDownPaymentPercent": 15,
    "maxDownPaymentPercent": 50,
    "minDownPaymentAmount": 300000.00,
    "maxDownPaymentAmount": 1000000.00,
    "financedAmount": 1600000.00,
    "monthlyPaymentAmount": 146666.67,
    "totalInterestAmount": 160000.00,
    "totalAmount": 2160000.00,
    "currency": "TZS",
    "firstPaymentDate": "2025-11-17T00:00:00",
    "lastPaymentDate": "2026-10-17T00:00:00",
    "schedule": [
      {
        "paymentNumber": 1,
        "dueDate": "2025-11-17T00:00:00",
        "amount": 146666.67,
        "principalPortion": 126666.67,
        "interestPortion": 20000.00,
        "remainingBalance": 1473333.33,
        "description": "Month 1 payment"
      },
      {
        "paymentNumber": 2,
        "dueDate": "2025-12-17T00:00:00",
        "amount": 146666.67,
        "principalPortion": 128250.00,
        "interestPortion": 18416.67,
        "remainingBalance": 1345083.33,
        "description": "Month 2 payment"
      },
      {
        "paymentNumber": 3,
        "dueDate": "2026-01-17T00:00:00",
        "amount": 146666.67,
        "principalPortion": 129853.13,
        "interestPortion": 16813.54,
        "remainingBalance": 1215230.20,
        "description": "Month 3 payment"
      },
      {
        "paymentNumber": 12,
        "dueDate": "2026-10-17T00:00:00",
        "amount": 146666.67,
        "principalPortion": 144833.33,
        "interestPortion": 1833.34,
        "remainingBalance": 0.00,
        "description": "Final payment"
      }
    ],
    "comparison": {
      "payingUpfront": 2000000.00,
      "payingWithInstallment": 2160000.00,
      "additionalCost": 160000.00,
      "additionalCostPercent": 8.00
    },
    "fulfillmentTiming": "IMMEDIATE",
    "fulfillmentDescription": "Product ships immediately after down payment"
  }
}

Success Response Fields:

Field	Description
planId	ID of the plan used
planName	Name of the plan
planDescription	Description of the plan
paymentFrequency	Human-readable payment frequency
numberOfPayments	Total number of payments
durationDisplay	Human-readable duration
apr	Annual Percentage Rate
gracePeriodDays	Grace period before first payment
productPrice	Per-unit product price
quantity	Quantity purchased
totalProductCost	Total product cost (price × quantity)
downPaymentPercent	Chosen down payment percentage
downPaymentAmount	Calculated down payment amount
minDownPaymentPercent	Minimum allowed down payment %
maxDownPaymentPercent	Maximum allowed down payment % (50%)
minDownPaymentAmount	Minimum down payment amount
maxDownPaymentAmount	Maximum down payment amount
financedAmount	Amount being financed (after down payment)
monthlyPaymentAmount	Each installment payment amount
totalInterestAmount	Total interest to be paid
totalAmount	Grand total (product + interest)
currency	Currency code (TZS)
firstPaymentDate	When first payment is due
lastPaymentDate	When last payment is due
schedule	Array of payment schedule items
schedule[].paymentNumber	Payment number (1, 2, 3...)
schedule[].dueDate	When payment is due
schedule[].amount	Payment amount
schedule[].principalPortion	Amount going to principal
schedule[].interestPortion	Amount going to interest
schedule[].remainingBalance	Balance after this payment
schedule[].description	Payment description
comparison	Comparison information object
comparison.payingUpfront	Cost if paying full price now
comparison.payingWithInstallment	Total cost with installment
comparison.additionalCost	Extra cost (interest)
comparison.additionalCostPercent	Interest as % of product price
fulfillmentTiming	When product ships
fulfillmentDescription	Description of fulfillment timing

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Down payment must be at least 15% for this plan",
  "action_time": "2025-10-18T10:30:45",
  "data": "Down payment must be at least 15% for this plan"
}

Standard Error Types:

Application-Level Exceptions (400-499)

• 400 BAD_REQUEST: Invalid down payment percentage, inactive plan, or business rule violation
• 404 NOT_FOUND: Plan not found
• 422 UNPROCESSABLE_ENTITY: Validation errors on request parameters

Error Response Examples:

Bad Request - Down Payment Too Low (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Down payment must be at least 15% for this plan",
  "action_time": "2025-10-18T10:30:45",
  "data": "Down payment must be at least 15% for this plan"
}

Bad Request - Down Payment Too High (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Down payment cannot exceed 50%",
  "action_time": "2025-10-18T10:30:45",
  "data": "Down payment cannot exceed 50%"
}

Bad Request - Plan Not Active (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "This installment plan is not currently available",
  "action_time": "2025-10-18T10:30:45",
  "data": "This installment plan is not currently available"
}

Not Found - Plan (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Installment plan not found with ID: 5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "action_time": "2025-10-18T10:30:45",
  "data": "Installment plan not found with ID: 5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-18T10:30:45",
  "data": {
    "planId": "Plan ID is required",
    "productPrice": "Product price must be greater than 0",
    "downPaymentPercent": "must be between 10 and 50"
  }
}

---

Quick Reference Guide

HTTP Method Badge Code Templates

GET Badge:

<span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span>

POST Badge:

<span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span>

Common HTTP Status Codes

• 200 OK: Successful GET/POST request
• 400 Bad Request: Invalid request data or business logic violation
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error

Payment Frequency Types

• DAILY: Payment every day
• WEEKLY: Payment every week (7 days)
• BI_WEEKLY: Payment every 2 weeks (14 days)
• SEMI_MONTHLY: Payment twice per month (1st and 15th)
• MONTHLY: Payment every month (30 days)
• QUARTERLY: Payment every 3 months (90 days)
• CUSTOM_DAYS: Payment at custom interval (specified in customFrequencyDays)

Fulfillment Timing Options

• IMMEDIATE: Product ships immediately after down payment is made. Customer gets product while paying installments.
• AFTER_PAYMENT: Product ships only after final payment is completed (layaway model). Inventory is held during payment period.

Down Payment Rules

• Minimum: Set by individual plan (typically 10-20%)
• Maximum: 50% (platform-wide limit)
• Validation: Customer's choice must be within min-max range
• Purpose: Reduces financed amount and total interest paid

APR (Annual Percentage Rate)

• Expressed as percentage (e.g., 15.00 = 15%)
• Range: 0% to 36% (platform limits)
• Converted to period rate based on payment frequency
• Used in amortization calculation for each payment

Financial Calculations

Amortization Formula

Monthly Payment = P × [r(1+r)^n] / [(1+r)^n - 1]

Where:

• P = Principal (financed amount)
• r = Period rate (APR / periods per year)
• n = Number of payments

Period Rate Calculation

• Daily: APR / 365
• Weekly: APR / 52
• Bi-weekly: APR / 26
• Semi-monthly: APR / 24
• Monthly: APR / 12
• Quarterly: APR / 4
• Custom: APR / (365 / customDays)

Payment Breakdown

Each payment consists of:

1. Interest Portion: Remaining balance × period rate
2. Principal Portion: Payment amount - interest portion
3. Remaining Balance: Previous balance - principal portion

Schedule Generation

• First payment due after grace period
• Subsequent payments calculated based on frequency
• Last payment adjusted for rounding differences
• All dates in ISO 8601 format

Comparison Information

Shows cost difference between:

• Paying upfront: Original product price
• Paying with installment: Product price + total interest
• Additional cost: Total interest amount
• Additional cost %: Interest as percentage of product price

Common Use Cases

1. Display Plans on Product Page

GET /api/v1/installments/products/{productId}/plans

• Shows all active plans for product
• Displays preview calculations at minimum down payment
• Highlights featured plans
• Sorted by displayOrder

2. Calculate Custom Preview

POST /api/v1/installments/calculate-preview
{
  "planId": "...",
  "productPrice": 2000000.00,
  "quantity": 1,
  "downPaymentPercent": 25
}

• Customer adjusts down payment slider
• Real-time calculation of payments
• Shows full payment schedule
• Displays savings comparison

3. Pre-Checkout Validation

POST /api/v1/installments/calculate-preview

• Validates customer's choices before checkout
• Ensures plan is still active
• Confirms down payment within range
• Generates schedule for agreement creation

Integration Examples

Frontend Flow

1. Product page loads → Call GET /products/{id}/plans
2. Display plan options with previews
3. User selects plan and adjusts down payment
4. Call POST /calculate-preview on down payment change
5. Show detailed breakdown and schedule
6. User proceeds to checkout with selected configuration

Mobile App Flow

1. Fetch plans when user taps "Installment Options"
2. Show plan cards with key metrics
3. Tapped plan shows full preview
4. Slider for down payment percentage
5. Real-time preview updates
6. "Continue to Checkout" with configuration

Error Handling Best Practices

Client-Side Validation

• Validate down payment range before API call
• Check quantity = 1 for installment
• Ensure product price > 0
• Validate UUID formats

Server-Side Errors

• 400: Show user-friendly message, allow retry
• 404: Product/plan not found, redirect or show alternatives
• 422: Display field-specific validation errors
• 500: Generic error message, log for investigation

Performance Considerations

• Cache plan data (TTL: 1 hour)
• Debounce preview calculations (300ms)
• Lazy load full schedules
• Optimize for mobile networks

Testing Scenarios

Happy Path

1. Get plans for valid product with installment enabled
2. Calculate preview with valid parameters
3. Verify calculations match expected values

Edge Cases

1. Product with no active plans → empty array
2. Product with installment disabled → empty array
3. Down payment at minimum boundary
4. Down payment at maximum boundary (50%)
5. Inactive plan in preview request → error

Error Cases

1. Invalid product ID → 404
2. Invalid plan ID → 404
3. Down payment too low → 400
4. Down payment too high → 400
5. Missing required fields → 422
6. Invalid data types → 422

Data Format Standards

• Dates: ISO 8601 format (2025-10-18T14:30:00Z)
• Currency: TZS (Tanzanian Shillings), no currency symbol in API
• Decimals: 2 decimal places for all monetary values
• Percentages: Whole numbers (15 = 15%, not 0.15)
• UUIDs: Standard UUID v4 format with hyphens

Business Rules Summary

1. One Item Per Agreement: Installment limited to single product
2. Active Plans Only: Only active plans returned in public endpoints
3. Down Payment Range: 10-50% (plan minimum to platform maximum)
4. APR Limits: 0-36% (platform enforced)
5. Grace Period: 0-60 days (plan-specific)
6. Payment Frequency: All standard frequencies supported
7. Fulfillment Options: IMMEDIATE or AFTER_PAYMENT
8. Currency: TZS only (Tanzania market)
9. Rounding: All calculations rounded to 2 decimal places
10. Early Payoff: 75% discount on remaining interest (not shown in preview)

Notes for Developers

Calculation Accuracy

• Use decimal/numeric types for currency calculations
• Avoid floating-point arithmetic
• Round to 2 decimals at final step only
• Last payment absorbs rounding differences

Caching Strategy

• Cache plan data per product (1 hour TTL)
• Invalidate cache when plans updated
• Preview calculations should not be cached
• Consider CDN for plan endpoints

Mobile Optimization

• Minimize payload size (exclude schedule if not needed)
• Compress responses (gzip/brotli)
• Use pagination for long schedules
• Implement request debouncing

Security Considerations

• No authentication required for public endpoints
• Rate limiting: 1000 requests/hour per IP
• Input validation on all parameters
• SQL injection prevention (parameterized queries)
• XSS prevention (sanitize all inputs)

Support & Resources

• API Documentation: https://docs.nextgate.com/api/installments
• Developer Portal: https://developers.nextgate.com
• Support Email: api-support@nextgate.com
• Status Page: https://status.nextgate.com
• Changelog: https://docs.nextgate.com/changelog

Documentation Checklist

Before using this API, ensure you understand:

• Public Access: No authentication required
• Plan Filtering: Only active plans returned
• Down Payment Rules: Min (plan-specific) to Max (50%)
• APR Calculation: Converted to period rate automatically
• Amortization: Principal + interest breakdown per payment
• Schedule Generation: All payment dates calculated
• Fulfillment Options: IMMEDIATE vs AFTER_PAYMENT
• Currency: TZS only
• Rounding: 2 decimal places
• Error Handling: Proper validation and error messages
• Rate Limiting: 1000 requests/hour per IP
• Caching: Recommended for plan data
• Testing: Sandbox environment available

---