Stripe Integration

The Billing API integrates with Stripe for payment processing and subscription management.

Get Stripe Customer Portal URL

Get a secure Stripe Customer Portal URL for billing management. Only account owners can access the customer portal.

Endpoint: https://apis.threatwinds.com/api/billing/v1/stripe/customer

Method: GET

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication

Note: You must use either Authorization header OR API key/secret combination.

Required Roles

Required role: owner

Only the account owner can access the Stripe Customer Portal.

Request

To get the customer portal URL, use a GET request:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/stripe/customer' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/stripe/customer' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'api-secret: your-api-secret'

Response

Success Response (200 OK)

{
  "url": "https://billing.stripe.com/b/1MdsfD..."
}

Response Schema

Field	Type	Description
url	string	Secure Stripe Customer Portal URL

Customer Portal Features

The Stripe Customer Portal allows customers to:

• View Invoices: Access and download all past invoices
• Update Payment Methods: Add, update, or remove payment methods
• Change Subscription: Upgrade or downgrade subscription tiers
• View Billing History: See complete payment and billing history
• Cancel Subscription: Cancel active subscriptions

Error Codes

Status Code	Description	Possible Cause
200	OK	Portal URL generated successfully
400	Bad Request	Invalid request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Not owner (insufficient permissions)
404	Not Found	Customer not found
500	Internal Server Error	Server error

---

Example Workflows

Workflow 1: Create Customer and Subscribe

# 1. User creates customer account
curl -X 'POST' \
  'https://apis.threatwinds.com/api/billing/v1/customer' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"email": "john@example.com"}'

# 2. Customer is created with a default tier subscription

Workflow 2: Change Subscription via Customer Portal

# 1. Owner gets customer portal URL
curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/stripe/customer' \
  -H 'Authorization: Bearer <token>'

# Response:
# {
#   "url": "https://billing.stripe.com/b/..."
# }

# 2. User opens URL in browser
# 3. User changes subscription tier in the portal
# 4. Tier and limits are updated automatically

Workflow 3: Handle Failed Payment

1. Payment attempt fails
   ↓
2. Subscription status changes to "past_due"
   ↓
3. Customer access may be restricted based on status
   ↓
4. Customer updates payment method in portal
   ↓
5. Payment succeeds and subscription status returns to "active"

---

Best Practices

For Application Developers

1. Check Subscription Status: Always check customer subscription status before granting access
2. Test with Stripe Test Mode: Use Stripe test mode during development

For Customer Portal

1. Direct to Portal: Send owners to Stripe Customer Portal for subscription changes
2. Don’t Duplicate UI: Don’t recreate billing UI - use Stripe’s portal
3. Handle Returns: Configure return URL in Stripe to bring users back to your app
4. Communicate Status: Show subscription status in your application UI

Security Considerations

1. Restrict Portal Access: Only allow owners to access customer portal
2. Secure API Keys: Never expose Stripe secret keys in frontend code

---

Troubleshooting

Common Issues

Issue	Cause	Solution
Customer portal access denied	User not owner	Only owners can access portal
Subscription not reflecting changes	Processing delay	Wait a few moments for the change to take effect