Checkout & Payments

Overview

The Checkout API enables you to create secure payment sessions for FitAiid products using Stripe. This endpoint handles product purchases, subscription plans, and digital fitness content.

All payment processing is handled securely through Stripe. FitAiid never stores sensitive payment information.

Create Checkout Session

Headers

Authorization

string

required

Bearer token: Bearer YOUR_JWT_TOKEN

Body Parameters

items

array

required

Array of products to purchase

Show item object structure

productId

string

required

MongoDB ObjectId of the product

quantity

integer

required

Quantity to purchase (1-100)

successUrl

string

required

URL to redirect after successful payment

cancelUrl

string

required

URL to redirect if payment is cancelled

shippingAddress

object

required

Shipping address information

Show properties

firstName

string

required

First name (max 50 characters)

lastName

string

required

Last name (max 50 characters)

street

string

required

Street address (max 200 characters)

city

string

required

City name (max 100 characters)

state

string

required

State/Department (max 100 characters)

zipCode

string

Postal code (max 10 characters)

country

string

default:"Colombia"

Country name

phone

string

required

Colombian phone number (format: +573XXXXXXXXX)

shippingMethod

string

default:"standard"

Shipping method selection

Show options

standard - Standard shipping (5 days) - $25,000 COP
express - Express shipping (3 days) - $45,000 COP
overnight - Overnight delivery (1 day) - $75,000 COP
pickup - In-store pickup - Free

couponCode

string

Discount coupon code

customerNotes

string

Special delivery instructions (max 500 characters)

Response

curl -X POST https://api.fitaiid.com/api/checkout/create-session \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "507f1f77bcf86cd799439011",
        "quantity": 2
      },
      {
        "productId": "507f1f77bcf86cd799439012",
        "quantity": 1
      }
    ],
    "shippingAddress": {
      "firstName": "Carlos",
      "lastName": "Rodriguez",
      "street": "Calle 123 #45-67",
      "city": "Bogotá",
      "state": "Cundinamarca",
      "zipCode": "110111",
      "country": "Colombia",
      "phone": "+573001234567"
    },
    "shippingMethod": "express",
    "successUrl": "https://fitaiid.com/checkout/success",
    "cancelUrl": "https://fitaiid.com/checkout/cancel",
    "customerNotes": "Please deliver in the afternoon"
  }'

After receiving the response, redirect the user to the checkoutUrl to complete payment on Stripe’s secure checkout page.

Verify Payment Status

Path Parameters

sessionId

string

required

Stripe checkout session ID returned from create-session

Response

curl -X GET https://api.fitaiid.com/api/checkout/verify/cs_test_a1b2c3d4e5f6... \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Apply Coupon Code

Body Parameters

couponCode

string

required

Coupon code to validate

items

array

required

Array of cart items to calculate discount

Response

curl -X POST https://api.fitaiid.com/api/checkout/apply-coupon \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "couponCode": "FITAIID20",
    "items": [
      {"productId": "507f1f77bcf86cd799439011", "quantity": 2}
    ]
  }'

Stripe Webhook Handler

This endpoint is called directly by Stripe and should not be called by clients. It requires Stripe signature verification.

Webhook Events Handled

checkout.session.completed

Triggered when a customer completes the checkout session

Creates order record in database
Updates product inventory
Sends confirmation email
Updates payment status to paid

checkout.session.expired

Triggered when a checkout session expires

Updates order status to cancelled
Releases reserved inventory

payment_intent.succeeded

Triggered when payment is successfully processed

Confirms order status
Triggers fulfillment workflow

payment_intent.payment_failed

Triggered when payment fails

Updates payment status to failed
Sends payment failure notification

charge.refunded

Triggered when a charge is refunded

Updates order status to refunded
Restores product inventory
Sends refund confirmation

Configuration

To set up the webhook in your Stripe dashboard:

Go to Developers → Webhooks in Stripe Dashboard
Click Add endpoint
Enter URL: https://api.fitaiid.com/api/checkout/webhook
Select events to listen for:
- checkout.session.completed
- checkout.session.expired
- payment_intent.succeeded
- payment_intent.payment_failed
- charge.refunded
Copy the Signing secret and add to your environment variables as STRIPE_WEBHOOK_SECRET

Security

Webhook Signature Verification

All webhook requests are verified using Stripe’s signature in the stripe-signature header. Requests without valid signatures are rejected.

Calculate Shipping Cost

Body Parameters

items

array

required

Array of cart items

shippingMethod

string

required

Desired shipping method: standard, express, overnight, or pickup

city

string

required

Delivery city for location-based calculations

Response

{
  "success": true,
  "shippingMethod": "express",
  "shippingCost": 45000,
  "formattedCost": "$45,000",
  "estimatedDays": 3,
  "carrier": "Servientrega",
  "freeShippingThreshold": 200000,
  "amountToFreeShipping": 0,
  "isFreeShipping": false
}

Orders over $200,000 COP qualify for free standard shipping. Express and overnight shipping incur additional charges.

Error Responses

400 Bad Request

Invalid request parameters

Show examples

Product out of stock
Invalid shipping address
Quantity exceeds limit
Invalid coupon code

401 Unauthorized

Missing or invalid authentication token

404 Not Found

Product or checkout session not found

500 Internal Server Error

Stripe API error or server issue

Testing

Test Cards

Use these test card numbers in Stripe test mode:

Successful Payment

Card Number: 4242 4242 4242 4242Expiry: Any future dateCVC: Any 3 digits

Payment Declined

Card Number: 4000 0000 0000 0002Use this to test declined payments

3D Secure Required

Card Number: 4000 0027 6000 3184Use this to test Strong Customer Authentication

See Stripe Testing Documentation for more test scenarios.

Authentication

Workouts

User Management

Notifications

Payments

Checkout & Payments

Overview

Create Checkout Session

Headers

Body Parameters

Response

Verify Payment Status

Path Parameters

Response

Apply Coupon Code

Body Parameters

Response

Stripe Webhook Handler

Webhook Events Handled

Configuration

Security

Webhook Signature Verification

Calculate Shipping Cost

Body Parameters

Response

Error Responses

Testing

Test Cards

Successful Payment

Payment Declined

3D Secure Required

Build docs developers (and LLMs) love

Authentication

Workouts

User Management

Notifications

Payments

​Overview

​Create Checkout Session

​Headers

​Body Parameters

​Response

​Verify Payment Status

​Path Parameters

​Response

​Apply Coupon Code

​Body Parameters

​Response

​Stripe Webhook Handler

​Webhook Events Handled

​Configuration

​Security

Webhook Signature Verification

​Calculate Shipping Cost

​Body Parameters

​Response

​Error Responses

​Testing

​Test Cards

Successful Payment

Payment Declined

3D Secure Required

Build docs developers (and LLMs) love

Overview

Create Checkout Session

Headers

Body Parameters

Response

Verify Payment Status

Path Parameters

Response

Apply Coupon Code

Body Parameters

Response

Stripe Webhook Handler

Webhook Events Handled

Configuration

Security

Calculate Shipping Cost

Body Parameters

Response

Error Responses

Testing

Test Cards