Skip to main content
POST
/
api
/
payments
/
create-checkout
Create checkout session
curl --request POST \
  --url https://api.example.com/api/payments/create-checkout \
  --header 'Authorization: <authorization>'
{
  "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

​
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 --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.

Build docs developers (and LLMs) love

Get started for freeTalk to us