Create checkout session

Start a Stripe checkout flow to upgrade a user to the Pro plan.

POST /api/payments/create-checkout

Create checkout session

cURL

curl --request POST \
  --url https://api.example.com/api/payments/create-checkout \
  --header 'Authorization: <authorization>'

200

{
  "message": "<string>",
  "data": {
    "url": "<string>"
  }
}

This endpoint requires a valid Bearer token. Unauthenticated requests return 401 Unauthorized.

Creates a Stripe Checkout Session for the authenticated user and returns a short-lived redirect URL. Once the user completes payment on the Stripe-hosted page, their account is automatically upgraded to Pro via the webhook handler.

Authentication

All requests to this endpoint must include a Authorization: Bearer <token> header. The token is issued at login.

Request

This endpoint does not accept a request body. The user’s identity and email address are derived from the authenticated session.

Authorization · string · required

Bearer token obtained from login or OAuth. Format: Bearer <token>.

Response

On success the server returns 200 OK with a JSON body containing a single-use Stripe Checkout URL.

message · string

Human-readable status message.

data · object

Hide properties

url · string · required

The Stripe-hosted checkout URL. Redirect the user to this address to complete payment. The URL is valid for a short time and can only be used once.

Behavior

• The checkout session is created for a monthly Pro subscription.
• Promotion codes are accepted on the Stripe-hosted page.
• After a successful payment, Stripe fires a checkout.session.completed webhook event. The webhook handler upgrades the user’s plan in the database — no action is needed on the client beyond redirecting the user.
• On cancellation, Stripe redirects the user to the frontend /payment/cancel page. No charge is made.

The returned url is single-use. Do not cache or reuse it. If the user navigates away without completing payment, call this endpoint again to get a fresh URL.

Example

cURL

curl --request POST \
  --url https://api.hayon.app/api/payments/create-checkout \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Success response

{
  "message": "Checkout session created",
  "data": {
    "url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6#fidkdWxOYHwnPyd1blpxYHZxWjA0"
  }
}

Error responses

401

{
  "message": "Unauthorized"
}

500

{
  "message": "Payment session creation failed"
}

Checkout flow

1. Request a checkout URL

   Call POST /api/payments/create-checkout with the user’s Bearer token.

2. Redirect the user

   Redirect the browser to the url returned in the response body.

3. User completes payment

   Stripe handles card collection and 3DS authentication on its hosted page.

4. Webhook upgrades the account

   Stripe sends a checkout.session.completed event to POST /api/payments/webhook. The server upgrades the user’s plan to Pro and sets subscription period dates.

5. User lands on success page

   Stripe redirects the user to /payment/success?session_id=... on the frontend.