Stripe Integration

Accept credit cards, Apple Pay, Google Pay, and 40+ payment methods globally using Stripe as your payment provider.

Prerequisites

Before you begin, make sure you have:

A Stripe account — sign up at stripe.com if you don’t have one
Your Stripe API keys from the Stripe Dashboard
A working Headless Commerce store with at least one product

Use test mode keys (sk_test_... / pk_test_...) during development. Switch to live keys only when you’re ready to accept real payments.

Environment Variables

Add the following environment variables to your API server:

# Stripe secret key (server-side only — never expose this to the client)
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

# Stripe webhook signing secret (from the Stripe Dashboard → Webhooks)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx

For your frontend application, add the publishable key:

# Stripe publishable key (safe for client-side usage)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Never expose STRIPE_SECRET_KEY or STRIPE_WEBHOOK_SECRET to the client. These must only be used server-side.

Checkout Flow

The complete Stripe checkout flow involves four steps: creating a cart, initiating checkout, confirming payment on the client, and handling the webhook confirmation.

Webhook Setup

Headless Commerce listens for Stripe webhook events to keep order and payment statuses in sync. Configure webhooks in the Stripe Dashboard:

Go to Developers → Webhooks in the Stripe Dashboard
Click Add endpoint
Enter your webhook URL: https://api.headlesscommerce.io/v1/webhooks/stripe
Select the following events:
- payment_intent.succeeded
- payment_intent.payment_failed
- charge.refunded
- charge.dispute.created
Copy the Signing secret and set it as STRIPE_WEBHOOK_SECRET

Event handling

Stripe Event	Headless Commerce Action
`payment_intent.succeeded`	Order status set to `confirmed`, payment marked `completed`
`payment_intent.payment_failed`	Payment marked `failed`, `payment.failed` webhook sent
`charge.refunded`	Refund recorded, `payment.refunded` webhook sent
`charge.dispute.created`	Order flagged for review

Refunds

Issue full or partial refunds through the Admin API:

import { createAdminClient } from '@headless-commerce/sdk';

const admin = createAdminClient({
  apiKey: process.env.HC_ADMIN_API_KEY!,
});

// Full refund
const refund = await admin.orders.refund('order_xxxxxxxx', {
  reason: 'customer_request',
});

// Partial refund
const partialRefund = await admin.orders.refund('order_xxxxxxxx', {
  amount: 1500,
  reason: 'Item damaged during shipping',
});

import requests

admin_url = "https://api.headlesscommerce.io/v1"
admin_headers = {
    "Authorization": "Bearer sk_test_your_key",
    "Content-Type": "application/json",
}

# Full refund
refund = requests.post(
    f"{admin_url}/admin/orders/order_xxxxxxxx/refunds",
    headers=admin_headers,
    json={"reason": "customer_request"},
).json()

# Partial refund
partial_refund = requests.post(
    f"{admin_url}/admin/orders/order_xxxxxxxx/refunds",
    headers=admin_headers,
    json={"amount": 1500, "reason": "Item damaged during shipping"},
).json()

# Full refund
curl -X POST https://api.headlesscommerce.io/v1/admin/orders/{orderId}/refunds \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "customer_request"}'

# Partial refund
curl -X POST https://api.headlesscommerce.io/v1/admin/orders/{orderId}/refunds \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "reason": "Item damaged during shipping"
  }'

The refund is processed through Stripe automatically and the order is updated accordingly.

Testing

Test mode keys

Always use test mode API keys during development. These keys create test-only transactions that never hit real payment networks.

Key type	Prefix	Example
Publishable key	`pk_test_`	`pk_test_51ABC...`
Secret key	`sk_test_`	`sk_test_51ABC...`

Test card numbers

Use these card numbers in test mode:

Card Number	Scenario
`4242 4242 4242 4242`	Successful payment
`4000 0000 0000 3220`	3D Secure authentication required
`4000 0000 0000 9995`	Payment declined (insufficient funds)
`4000 0000 0000 0002`	Generic card decline

Use any future expiration date, any 3-digit CVC, and any postal code.

Testing webhooks locally

Use the Stripe CLI to forward webhook events to your local development server:

# Install the Stripe CLI
brew install stripe/stripe-cli/stripe

# Login to your Stripe account
stripe login

# Forward events to your local endpoint
stripe listen --forward-to localhost:3000/v1/webhooks/stripe

# In another terminal, trigger a test event
stripe trigger payment_intent.succeeded

Error Handling

Handle payment errors gracefully in your frontend:

try {
  const order = await client.carts.checkout(cart.id, {
    email: 'customer@example.com',
    shipping_address: { /* ... */ },
    payment_method: 'stripe',
  });
} catch (error: unknown) {
  if (error instanceof Error && 'code' in error) {
    const apiError = error as { code: string; message: string };
    switch (apiError.code) {
      case 'cart_empty':
        // Cart has no items
        break;
      case 'insufficient_stock':
        // One or more items are out of stock
        break;
      case 'payment_provider_error':
        // Stripe returned an error during PaymentIntent creation
        break;
      default:
        // Unexpected error
        console.error(apiError.message);
    }
  }
}

try:
    order = requests.post(
        f"{base_url}/storefront/carts/{cart_id}/checkout",
        headers=headers,
        json={
            "email": "customer@example.com",
            "shipping_address": { ... },
            "payment_method": "stripe",
        },
    )
    order.raise_for_status()
except requests.exceptions.HTTPError as e:
    error = e.response.json()
    code = error.get("code")
    if code == "cart_empty":
        pass  # Cart has no items
    elif code == "insufficient_stock":
        pass  # One or more items are out of stock
    elif code == "payment_provider_error":
        pass  # Stripe returned an error
    else:
        print(error.get("message"))

Common Stripe-specific errors after confirmPayment():

Error Code	Description	Suggested Action
`card_declined`	The card was declined	Ask customer to use a different card
`expired_card`	The card has expired	Ask customer to update card details
`insufficient_funds`	Insufficient funds	Ask customer to use a different card
`processing_error`	Processing error at Stripe	Retry the payment
`incorrect_cvc`	Incorrect CVC	Ask customer to re-enter CVC

Next Steps

Webhooks

Learn about all webhook events and payload formats.

TossPayments

Set up TossPayments for Korean payment methods.

API Reference

Explore all checkout and payment endpoints.

SDKs

Full SDK reference with every resource and method.

Getting Started

Build with AI

API Conventions

Security

Integration Guides

Recipes

Stripe Integration

Stripe Integration

Prerequisites

Environment Variables

Checkout Flow

Webhook Setup

Event handling

Refunds

Testing

Test mode keys

Test card numbers

Testing webhooks locally

Error Handling

Next Steps

Webhooks

TossPayments

API Reference

SDKs

​Stripe Integration

​Prerequisites

​Environment Variables

​Checkout Flow

​Webhook Setup

​Event handling

​Refunds

​Testing

​Test mode keys

​Test card numbers

​Testing webhooks locally

​Error Handling

​Next Steps

Webhooks

TossPayments

API Reference

SDKs

Stripe Integration

Prerequisites

Environment Variables

Checkout Flow

Webhook Setup

Event handling

Refunds

Testing

Test mode keys

Test card numbers

Testing webhooks locally

Error Handling

Next Steps