Checkout

Browser (SDK)  →  Checkout service  →  PSP
                       ↑
      /<api>/checkout/session  (creates Checkout Session from cart)
                       ↑
      commercetools Sessions API  (POST https://session.{region}.commercetools.com/{projectKey}/sessions)

# The key of your Checkout Application
CTP_CHECKOUT_APP_KEY=storefront-checkout

cd <root-dir> && npm install @commercetools/checkout-browser-sdk

// <root-dir>/<api-dir>/checkout/session/route.ts

const APP_KEY = process.env.CTP_CHECKOUT_APP_KEY!;

// Derive region from CTP_API_URL — no separate CT_REGION variable needed.
// https://api.us-central1.gcp.commercetools.com → us-central1.gcp
const REGION = API_URL.replace(/^https?:\/\/api\./, '').replace(/\.commercetools\.com\/?$/, '');

async function getManageSessionsToken(): Promise<string> {
  // fetch token from oauth/token?grant_type=client_credentials
  // use the full scope provided in .env vars
}

export async function POST() {
  // guard with session's cart ID

  try {
    const token = await getManageSessionsToken();
    const res = await fetch(
      `https://session.${REGION}.commercetools.com/${PROJECT_KEY}/sessions`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${token}`,
        },
        body: JSON.stringify({
          cart: { cartRef: { id: session.cartId } },
          metadata: { applicationKey: APP_KEY },
        }),
      },
    );
    // handle errors here
    const data = await res.json();
    // Return projectKey and region so the client component needs no frontend facing environment vars
    return NextResponse.json({ sessionId: data.id, projectKey: PROJECT_KEY, region: REGION });
  } catch (e: unknown) {
   // handle error
  }
}

// <root-dir>/components/checkout/StepPayment.tsx
'use client';
...
import { paymentFlow } from '@commercetools/checkout-browser-sdk';

export default function StepPayment() {
  // fetch checkout session
  useEffect(() => {
   // handle loading and single initialization

    (async () => {
      try {
        const { sessionId, projectKey, region } = await getCheckoutSession();


        paymentFlow({
          projectKey,
          region,
          sessionId,
          locale,           // from useLocale() — never hardcode
          onInfo: (msg) => {
            if (msg.code === 'checkout_completed') {
              router.push(<checkout-confirmation-path>);
            }
          },
          onError: (err) => {
            // SDK Message type has payload/code, not message
            setError(String(err.payload ?? err.code ?? 'Payment error'));
          },
        });
      } catch (e: unknown) {
       // handle errors
      }
    })();
  }, []); // eslint-disable-line react-hooks/exhaustive-deps

  return (
    <div>
      // display loading DOM
      {/* Required mount point — without this the widget occupies the full page */}
      <div data-ctc />
      // display errors
    </div>
  );
}

checkoutFlow({
  // ...
  styles: {
    '--font-family': 'var(--font-sans)',
    '--color-primary': '#2d2d2d',       // charcoal
    '--color-primary-hover': '#4a4a4a',
    '--border-radius': '0.125rem',      // rounded-sm
  },
});