Skip to main content

​
POST /api/create-checkout-session

Creates a Stripe checkout session for purchasing credits. Returns a URL to redirect the user to Stripe’s hosted checkout page.

​
Authentication

This endpoint requires authentication. Include valid Clerk authentication credentials in your request.

​
Request body

​
credits
number
required
The number of credits to purchase. Must be a positive integer (minimum 1).

​
Response

​
url
string
The Stripe checkout session URL to redirect the user to

​
Pricing

  • Price per credit: $1.25 USD
  • Payment methods: Credit/debit cards via Stripe
  • Total amount is calculated as: credits × $1.25

​
Code examples

curl -X POST https://gitread.dev/api/create-checkout-session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "credits": 10
  }'

​
Response example

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

​
Checkout session configuration

The Stripe checkout session includes:
  • Product name: {credits} Credits
  • Product description: Purchase {credits} credits for GitRead
  • Currency: USD
  • Success URL: Returns to /success?session_id={CHECKOUT_SESSION_ID}
  • Cancel URL: Returns to homepage /

​
Metadata

The following metadata is attached to the Stripe session:
​
userId
string
The Clerk user ID of the purchaser
​
credits
string
The number of credits being purchased (as a string)

​
Error responses

​
400
Bad Request
Invalid credits value
{
  "error": "Invalid credits value"
}
This error occurs when:
  • Credits value is not provided
  • Credits is not a number
  • Credits is less than 1
​
401
Unauthorized
Authentication required
{
  "error": "Unauthorized"
}
​
500
Internal Server Error
Error creating Stripe checkout session
{
  "error": "Error creating checkout session"
}

​
POST /api/verify-payment

Verifies a completed Stripe checkout session and adds the purchased credits to the user’s account. This endpoint should be called after the user returns from a successful Stripe checkout.

​
Authentication

This endpoint requires authentication. Include valid Clerk authentication credentials in your request.

​
Request body

​
sessionId
string
required
The Stripe checkout session ID to verify (obtained from the success URL)

​
Response

​
success
boolean
Indicates whether the payment was verified and credits were added

​
Code examples

curl -X POST https://gitread.dev/api/verify-payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{
    "sessionId": "cs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
  }'

​
Response example

{
  "success": true
}

​
Verification process

The endpoint performs the following checks:
  1. Authentication: Verifies the user is authenticated
  2. Session validation: Retrieves the Stripe session and validates it exists
  3. User matching: Ensures the session’s userId metadata matches the authenticated user
  4. Payment status: Confirms the payment status is paid
  5. Duplicate prevention: Checks if the session has already been processed
  6. Credit addition: Adds credits to user’s account
  7. Event tracking: Marks the session as processed to prevent double-crediting

​
Idempotency

This endpoint is idempotent. If the same session ID is verified multiple times:
  • The first call adds credits and returns {"success": true}
  • Subsequent calls detect the session was already processed and return {"success": true} without adding credits again
This prevents duplicate credit additions if the user refreshes the success page.

​
Error responses

​
400
Bad Request
Various validation errorsMissing session ID:
{
  "error": "Missing session ID"
}
Stripe session not found:
{
  "error": "Stripe session not found"
}
User ID mismatch:
{
  "error": "Invalid session"
}
Invalid credits amount:
{
  "error": "Invalid credits amount"
}
Payment not completed:
{
  "error": "Payment not completed"
}
​
401
Unauthorized
Authentication required
{
  "error": "Unauthorized"
}
​
500
Internal Server Error
Error during payment verification or credit addition
{
  "error": "Error verifying payment"
}
or with details:
{
  "error": "Error adding credits",
  "details": { ... }
}

{
  "error": "Error marking event as processed",
  "details": { ... }
}

​
Database operations

The endpoint performs the following database operations:
  1. Check processed events: Queries processed_stripe_events table to prevent duplicate processing
  2. Get current credits: Fetches user’s current credit balance
  3. Update credits: Uses upsert to add credits to the user’s account
  4. Record event: Inserts a record into processed_stripe_events with:
    • event_id: Format session_{sessionId}
    • user_id: Clerk user ID
    • credits: Number of credits purchased
    • processed_at: Current timestamp

​
Integration flow

  1. User clicks “Purchase Credits”
  2. Client calls /api/create-checkout-session
  3. Client redirects user to Stripe checkout URL
  4. User completes payment on Stripe
  5. Stripe redirects to /success?session_id=...
  6. Client calls /api/verify-payment with session ID
  7. Credits are added to user’s account
  8. User can now generate READMEs

Build docs developers (and LLMs) love

Get started for freeTalk to us