Everything you need to integrate Stripe billing into your SaaS. Authenticate with your project API key, make a few calls, and you're live.
All API requests (except health check and webhooks) require a project API key sent via the X-API-Key header.
API keys are generated in the PaymentPulse dashboard and are scoped per project. Each key uses the format pp_live_xxx.
All API endpoints are relative to:
All requests must use HTTPS. HTTP requests are redirected automatically.
/api/health
Returns service status. No authentication required. Returns JSON by default, or redirects to the status page if the client accepts HTML.
/api/checkout
Creates a Stripe Checkout session for a subscription. Automatically creates or reuses a Stripe customer record.
| Field | Type | Required | Description |
|---|---|---|---|
external_user_id |
string | Yes | Your application's user ID |
email |
string | Yes | Customer email address |
plan_slug |
string | Yes | Your plan identifier (e.g. professional) |
stripe_price_id |
string | Yes | Stripe Price ID (e.g. price_1AB2CD...) |
success_url |
string | Yes | Redirect URL after successful payment |
cancel_url |
string | Yes | Redirect URL if user cancels |
interval |
string | No | monthly or yearly (default: monthly) |
trial_days |
integer | No | Number of trial days before billing starts |
Redirect the user to the url to complete payment. Stripe handles the checkout UI.
/api/portal
Creates a Stripe Customer Portal session. Lets customers manage subscriptions, update payment methods, and view invoices.
| Field | Type | Required | Description |
|---|---|---|---|
external_user_id |
string | Yes | Your application's user ID |
return_url |
string | Yes | URL to return to after managing billing |
/api/subscription?external_user_id={id}
Returns the current subscription status for a user. Use this to gate features in your application.
| Parameter | Type | Required | Description |
|---|---|---|---|
external_user_id |
string | Yes | Your application's user ID |
| Status | Description |
|---|---|
active | Subscription is active and paid |
cancelling | Will cancel at end of current period |
cancelled | Subscription has ended |
past_due | Payment failed — retry pending |
unpaid | All payment retries exhausted |
trialing | In free trial period |
/api/customers/export
Exports all customers and their subscription data for your project. Supports JSON and CSV formats.
| Parameter | Type | Required | Description |
|---|---|---|---|
format |
string | No | json (default) or csv |
/api/webhook
PaymentPulse automatically receives and processes Stripe webhook events. You don't need to call this endpoint — Stripe sends events directly. All events are verified via Stripe signature and logged for audit.
| Event | Action |
|---|---|
checkout.session.completed |
Creates subscription record, links customer |
customer.subscription.updated |
Syncs status, period end, cancellation |
customer.subscription.deleted |
Marks subscription as cancelled |
invoice.payment_failed |
Marks subscription as past_due |
All webhook events are idempotent — replaying the same event has no effect.
All errors return a consistent JSON structure:
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request / invalid input |
401 | Missing or invalid API key |
403 | Forbidden (e.g. cross-project access) |
404 | Resource not found |
413 | Request body exceeds 1MB |
422 | Validation error — missing required field |
429 | Rate limited |
502 | Stripe API error |
503 | Service unavailable (Stripe not configured) |
Rate limits protect the service from abuse. Authenticated requests have higher limits.
| Type | Limit | Window |
|---|---|---|
| Authenticated (per project) | Higher | Per minute |
| Unauthenticated (per IP) | Stricter | Per minute |
When rate limited, the API returns 429 Too Many Requests. Back off and retry after a short delay.
Get your API key from the dashboard and start accepting payments in minutes.