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:

Interest Portion: Remaining balance × period rate
Principal Portion: Payment amount - interest portion
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

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

Mobile App Flow

Fetch plans when user taps "Installment Options"
Show plan cards with key metrics
Tapped plan shows full preview
Slider for down payment percentage
Real-time preview updates
"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

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

Edge Cases

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

Error Cases

Invalid product ID → 404
Invalid plan ID → 404
Down payment too low → 400
Down payment too high → 400
Missing required fields → 422
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

One Item Per Agreement: Installment limited to single product
Active Plans Only: Only active plans returned in public endpoints
Down Payment Range: 10-50% (plan minimum to platform maximum)
APR Limits: 0-36% (platform enforced)
Grace Period: 0-60 days (plan-specific)
Payment Frequency: All standard frequencies supported
Fulfillment Options: IMMEDIATE or AFTER_PAYMENT
Currency: TZS only (Tanzania market)
Rounding: All calculations rounded to 2 decimal places
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:

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

Installment Purchase - Public & Plan Endpoints

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Get Available Plans for Product

Application-Level Exceptions (400-499)

2. Calculate Installment Preview

Application-Level Exceptions (400-499)

Quick Reference Guide

HTTP Method Badge Code Templates

Common HTTP Status Codes

Payment Frequency Types

Fulfillment Timing Options

Down Payment Rules

APR (Annual Percentage Rate)

Financial Calculations

Amortization Formula

Period Rate Calculation

Payment Breakdown

Schedule Generation

Comparison Information

Common Use Cases

1. Display Plans on Product Page

2. Calculate Custom Preview

3. Pre-Checkout Validation

Integration Examples

Frontend Flow

Mobile App Flow

Error Handling Best Practices

Client-Side Validation

Server-Side Errors

Performance Considerations

Testing Scenarios

Happy Path

Edge Cases

Error Cases

Data Format Standards

Business Rules Summary

Notes for Developers

Calculation Accuracy

Caching Strategy

Mobile Optimization

Security Considerations

Support & Resources

Documentation Checklist