Billing Service

The Billing Service integrates Stripe payments into your application, allowing you to accept payments, manage subscriptions, and handle customer billing. All transactions use your own Stripe account for complete control and transparency.

What you can do:

  • Create checkout sessions for one-time purchases and subscriptions
  • Accept payments with custom UI using Payment Intents
  • Let customers manage their billing through self-service portal
  • Manage Stripe customers (create, read, update, delete)
  • Check customer subscription status and details
  • Process Stripe webhook events automatically

Interactive API Reference

For complete API documentation with interactive testing, visit our Swagger UI where you can try all endpoints with your own credentials.

View Interactive API Docs

Important: Before using the Billing API, configure your Stripe keys in the Billing Setup page. You'll need both test and live API keys from your Stripe dashboard.

Create Checkout Session

This is the quickest way to start accepting payments. Stripe hosts the entire checkout experience, handling payment collection, tax calculations, and PCI compliance. Your customer is redirected to Stripe's secure checkout page, then back to your app when complete. Perfect for getting started quickly or when you don't need custom payment UI. 

curl -X POST https://billing.stackfordevs.com/v1/stripe/checkout/session \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID" \\
  -d '{
    "line_items": [
      {
        "price": "price_1234567890",
        "quantity": 1
      }
    ],
    "mode": "payment",
    "success_url": "https://yourapp.com/success",
    "cancel_url": "https://yourapp.com/cancel",
    "customer_email": "customer@example.com"
  }'

Mode Options:

  • payment - One-time payment
  • subscription - Recurring subscription
  • setup - Save payment method for future use

Note: This endpoint requires both a Bearer token (to identify the buyer) and API keys (to identify your Stripe account). Add ?environment=test or ?environment=live to specify which Stripe keys to use.

Get Checkout Session Status

After creating a checkout session, use this endpoint to verify whether the customer completed their payment. This is useful when the customer returns to your success page, or when checking payment status from your backend before granting access to paid features. 

curl -X GET "https://billing.stackfordevs.com/v1/stripe/checkout/session/cs_test_abc123?environment=test" \\
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID"

Create Payment Intent

When you need a custom payment experience that matches your app's design, use Payment Intents with Stripe Elements. This keeps customers on your site while Stripe handles the secure payment processing behind the scenes. You control the UI, Stripe handles PCI compliance and fraud prevention. 

curl -X POST https://billing.stackfordevs.com/v1/stripe/payment/intent \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID" \\
  -d '{
    "amount": 2999,
    "currency": "usd",
    "description": "Purchase from YourApp",
    "receipt_email": "customer@example.com"
  }'

Response includes:

  • client_secret - Use with Stripe Elements on your frontend
  • payment_intent_id - Track payment status
  • status - Current payment status

Customer Portal

Give your customers a self-service billing dashboard where they can update payment methods, view invoices, and manage subscriptions—all without contacting support. This reduces support tickets and empowers customers to manage their own billing. Stripe hosts this portal, so there's nothing for you to build or maintain. 

curl -X POST https://billing.stackfordevs.com/v1/stripe/customer-portal/session \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID" \\
  -d '{
    "customer": "cus_1234567890",
    "return_url": "https://yourapp.com/account"
  }'

Customers can:

  • Update payment methods
  • View and download invoices
  • Cancel subscriptions
  • Update billing information
  • View subscription history

Customer Management

Manage Stripe customers programmatically. Create, retrieve, update, and delete customers in your Stripe account. Customers are automatically tagged with your tenant and project IDs for isolation.

Create Customer

curl -X POST https://billing.stackfordevs.com/v1/stripe/customers \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID" \\
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "description": "Premium customer",
    "phone": "+1234567890",
    "metadata": {
      "user_id": "user_123"
    }
  }'

List Customers

curl -X GET "https://billing.stackfordevs.com/v1/stripe/customers?limit=10&environment=test" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID"

Get Customer by ID

curl -X GET "https://billing.stackfordevs.com/v1/stripe/customers/cus_1234567890?environment=test" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID"

Update Customer

curl -X PUT https://billing.stackfordevs.com/v1/stripe/customers/cus_1234567890 \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID" \\
  -d '{
    "name": "Jane Doe",
    "description": "Updated description"
  }'

Delete Customer

curl -X DELETE "https://billing.stackfordevs.com/v1/stripe/customers/cus_1234567890?environment=test" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID"

Security: All customer endpoints include rate limiting (1,000 creates/hour, 5,000 queries/hour) and usage tracking. Customer metadata is automatically tagged with your tenant and project IDs.

Check Subscription Status

Query a customer's subscription status using their email address. This is useful for checking if a user has an active subscription before granting access to premium features, or for displaying subscription details in your app. 

curl -X GET "https://billing.stackfordevs.com/v1/customer/subscription?customerEmail=user@example.com&environment=test" \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "x-secret-key: YOUR_SECRET_KEY" \\
  -H "x-tenant-id: YOUR_TENANT_ID" \\
  -H "x-project-id: YOUR_PROJECT_ID"

Response (if subscription exists):

{
  "subscription": {
    "id": "sub_abc123",
    "tenantId": "YOUR_TENANT_ID",
    "planId": "price_premium",
    "status": "active",
    "currentPeriodEnd": "2025-12-30T23:59:59Z",
    "stripeSubscriptionId": "sub_1234567890",
    "cancelAtPeriodEnd": false,
    "plan": {
      "name": "Premium Plan"
    }
  }
}

Note: Returns subscription: null if the customer has no active subscription.

Environment Selection

All billing endpoints accept an environment query parameter to specify which Stripe API keys to use.

  • ?environment=test (default) - Uses your Stripe test keys (no real charges)
  • ?environment=live - Uses your Stripe live keys (real charges)

Important: Always test with environment=test during development. Only use environment=live in production.

Error Codes

The Billing API uses standard HTTP status codes and returns error details in the response body.

Status Description
400 Invalid request parameters or missing required fields
401 Missing or invalid authentication (API keys or Bearer token)
403 Access denied - Stripe not configured or invalid credentials
404 Resource not found (session, payment intent, customer, etc.)
500 Server error - Contact support if this persists