Payment MS API Documentation

GET /health

Health check endpoint (no authentication required)

Response:

{"status":"healthy","timestamp":"2025-11-21T10:00:00Z","service":"billing-service"}

GET /openapi.json

OpenAPI 3.0 specification (no authentication required)

POST /api/v1/checkout/subscription 🔒

Create a Stripe checkout session for a subscription

Request Body:

{
  "user_id": "user_123",
  "email": "customer@example.com",
  "product_id": "prod_RZaVDAN6Uf4Qfb",
  "price_id": "price_1QhEBSFhH6dwUiIH",
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

Response:

{
  "checkout_session_id": "cs_test_...",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
}

POST /api/v1/checkout/item 🔒

Create a Stripe checkout session for a single item purchase

Request Body:

{
  "user_id": "user_123",
  "email": "customer@example.com",
  "price_id": "price_1QhEBSFhH6dwUiIH",
  "quantity": 1,
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

Response:

{
  "checkout_session_id": "cs_test_...",
  "checkout_url": "https://checkout.stripe.com/..."
}

Notes:

quantity defaults to 1 if not specified. The price_id determines what product/service is being purchased.

POST /api/v1/checkout/cart 🔒

Create a checkout session for multiple items (shopping cart)

Request Body:

{
  "user_id": "user_123",
  "email": "customer@example.com",
  "items": [
    {"price_id": "price_ABC", "quantity": 2},
    {"price_id": "price_XYZ", "quantity": 1}
  ],
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/cancel"
}

Response:

{
  "checkout_session_id": "cs_test_...",
  "checkout_url": "https://checkout.stripe.com/..."
}

Notes:

Each item in the items array must have a price_id and quantity. Use this for multi-item purchases.

GET /api/v1/subscriptions/{user_id}/{product_id} 🔒

Get the subscription status for a user and product

URL Parameters:

user_id - User identifier
product_id - Stripe product ID

Response (Active):

{
  "status": "active",
  "subscription_id": "sub_1QhEBS...",
  "current_period_end": "2025-12-21T10:00:00Z",
  "product_id": "prod_RZaVDAN6Uf4Qfb"
}

Response (No Subscription):

{
  "status": "none",
  "subscription_id": "",
  "current_period_end": "0001-01-01T00:00:00Z",
  "product_id": ""
}

Status Values:

active, canceled, incomplete, incomplete_expired, past_due, trialing, unpaid, none

POST /api/v1/portal 🔒

Create a Stripe customer portal session for managing subscriptions

Request Body:

{
  "user_id": "user_123",
  "return_url": "https://yourapp.com/account"
}

Response:

{
  "portal_url": "https://billing.stripe.com/p/session/..."
}

Use Case:

Redirect users to portal_url to let them manage their subscriptions, update payment methods, view invoices, and cancel subscriptions.

🔐 Payment Microservice API

Public Endpoints

Protected Endpoints