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

Upgrade to Pro

Upgrade the customer account to the Pro plan with a 30-day free trial. This endpoint returns a Stripe Checkout URL where the user can complete the upgrade.

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

Method: POST

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.

Request Body 

{
  "successURL": "https://your-app.com/success",
  "cancelURL": "https://your-app.com/cancel"
}
Parameter Type Required Description
successURL string Yes URL to redirect the user after a successful checkout
cancelURL string Yes URL to redirect the user after a cancelled checkout

Required Roles

Required role: owner

Request

To generate an upgrade checkout URL, use a POST request:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/billing/v1/stripe/upgrade' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "successURL": "https://your-app.com/success",
  "cancelURL": "https://your-app.com/cancel"
}'

Response

Success Response (200 OK) 

{
  "checkoutURL": "https://checkout.stripe.com/c/pay/..."
}

Response Schema

Field Type Description
checkoutURL string The Stripe Checkout URL for completing the Pro upgrade

Error Codes

Status Code Description Possible Cause
200 OK Checkout URL generated successfully
400 Bad Request Invalid JSON or user not found
401 Unauthorized Missing or invalid authentication
403 Forbidden User is not the owner of the customer account
404 Not Found Customer not found or Pro tier not configured
500 Internal Server Error Server error during checkout session creation