Billing Endpoints

Manage subscriptions, payments, and billing with Stripe

Overview

Billing endpoints handle subscription management, checkout sessions, and payment processing through Stripe. These endpoints allow you to create subscriptions, manage billing portals, and handle webhooks.

All billing endpoints (except webhooks) require JWT authentication.

---

Create Checkout Session

POST · endpoint

/v1/billing/checkout

Create a Stripe Checkout session to subscribe an organization to a paid plan. This returns a checkout URL where users can complete payment.

Request Headers

Idempotency-Key · string

Optional idempotency key to prevent duplicate checkout sessions

Request Body

organization_id · string · required

Organization ID (UUID) to subscribe

price_id · string · required

Stripe Price ID (e.g., price_1234567890)

success_url · string · required

URL to redirect to after successful payment

cancel_url · string · required

URL to redirect to if user cancels

Response

session_id · string · required

Stripe Checkout Session ID

session_url · string · required

URL to redirect user to for checkout

client_secret · string · required

Client secret for embedded checkout (if applicable)

instant_update · boolean · required

true if subscription was updated immediately without checkout

Example

cURL

curl -X POST https://api.ryva.com/v1/billing/checkout \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-$(date +%s)" \
  -d '{
    "organization_id": "org-123e4567",
    "price_id": "price_1234567890",
    "success_url": "https://app.ryva.com/billing/success",
    "cancel_url": "https://app.ryva.com/billing/cancel"
  }'

Response

{
  "session_id": "cs_test_a1b2c3d4e5f6g7h8i9j0",
  "session_url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6g7h8i9j0",
  "client_secret": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_xyz",
  "instant_update": false
}

---

Verify Checkout Session

GET · endpoint

/v1/billing/session/:session_id

Verify a Stripe Checkout session after the user returns from checkout. This confirms payment status and subscription details.

Path Parameters

session_id · string · required

Stripe Checkout Session ID

Response

valid · boolean · required

Whether the session is valid and payment succeeded

session_id · string · required

Stripe Session ID

organization_id · string · required

Organization ID

plan · string · required

Subscription plan name

payment_status · string · required

Payment status: paid, unpaid, or no_payment_required

subscription_id · string

Stripe Subscription ID (if subscription created)

customer_email · string

Customer email from Stripe

amount_total · integer · required

Total amount paid in cents

currency · string · required

Currency code (e.g., usd)

Example

cURL

curl https://api.ryva.com/v1/billing/session/cs_test_a1b2c3d4 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Create Billing Portal Session

POST · endpoint

/v1/billing/portal

Create a Stripe Billing Portal session. This allows users to manage their subscription, payment methods, and invoices.

Request Body

organization_id · string · required

Organization ID (UUID)

return_url · string · required

URL to redirect to when user exits the portal

Response

session_url · string · required

URL to redirect user to for the billing portal

Example

cURL

curl -X POST https://api.ryva.com/v1/billing/portal \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org-123e4567",
    "return_url": "https://app.ryva.com/settings/billing"
  }'

---

Get Subscription Status

GET · endpoint

/v1/billing/organizations/:id/subscription

Retrieve the current subscription status for an organization.

Path Parameters

id · string · required

Organization ID (UUID)

Response

id · string · required

Subscription ID

organization_id · string · required

Organization ID

plan · string · required

Subscription plan: free, personal, or team

status · string · required

Subscription status: active, canceled, past_due, trialing, etc.

current_period_start · string · required

Start of current billing period

current_period_end · string · required

End of current billing period

cancel_at_period_end · boolean · required

Whether subscription will cancel at period end

canceled_at · string

When subscription was canceled (if applicable)

trial_start · string

Trial period start (if applicable)

trial_end · string

Trial period end (if applicable)

created_at · string · required

When subscription was created

updated_at · string · required

When subscription was last updated

Example

cURL

curl https://api.ryva.com/v1/billing/organizations/org-123e4567/subscription \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Cancel Subscription

POST · endpoint

/v1/billing/organizations/:id/subscription/cancel

Cancel an organization’s subscription. Can be set to cancel immediately or at the end of the billing period.

Path Parameters

id · string · required

Organization ID (UUID)

Request Body

cancel_at_period_end · boolean · required

If true, subscription continues until period end. If false, cancels immediately.

Response

id · string · required

Subscription ID

status · string · required

Updated subscription status

cancel_at_period_end · boolean · required

Whether subscription will cancel at period end

current_period_end · string · required

When the subscription will end

Example

cURL

curl -X POST https://api.ryva.com/v1/billing/organizations/org-123/subscription/cancel \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true
  }'

---

Stripe Webhooks

POST · endpoint

/v1/billing/webhooks/stripe

Receive and process Stripe webhook events. This endpoint is public but verified using Stripe signatures.

This endpoint should only be called by Stripe. It verifies webhook signatures to prevent unauthorized access.

Request Headers

Stripe-Signature · string · required

Stripe webhook signature for verification

Supported Events

The API handles the following Stripe webhook events:

• checkout.session.completed - Checkout session completed
• customer.subscription.created - New subscription created
• customer.subscription.updated - Subscription updated
• customer.subscription.deleted - Subscription canceled
• invoice.payment_succeeded - Payment succeeded
• invoice.payment_failed - Payment failed

Response

{
  "status": "success"
}

Configuration

Configure your Stripe webhook endpoint:

1. Go to Stripe Dashboard > Developers > Webhooks
2. Add endpoint: https://api.ryva.com/v1/billing/webhooks/stripe
3. Select events to send
4. Copy the webhook signing secret to your API configuration

---

Subscription Statuses

Status	Description
active	Subscription is active and in good standing
trialing	Subscription is in trial period
past_due	Payment failed, attempting to retry
canceled	Subscription has been canceled
unpaid	Payment failed and no more retry attempts
incomplete	Initial payment failed
incomplete_expired	Initial payment failed and grace period expired

---

Error Responses

Invalid Organization (404)

{
  "error": {
    "message": "Organization not found",
    "code": "NOT_FOUND",
    "status": 404
  }
}

No Active Subscription (404)

{
  "error": {
    "message": "No active subscription found",
    "code": "NOT_FOUND",
    "status": 404
  }
}

Stripe Error (500)

{
  "error": {
    "message": "Failed to create checkout session",
    "code": "INTERNAL_ERROR",
    "status": 500
  }
}