Checkout Security Update: Embedded Checkout Now Requires checkoutToken

Summary

We’ve introduced an additional security layer for Embedded Checkout by replacing raw checkout IDs in checkout sessions with opaque checkout tokens (ct_...).

This change strengthens authentication and prevents checkout sessions from being accessed using a predictable UUID alone. This update only affects Embedded Checkout (SDK) integrations.

What’s Changing

Previously, embedded checkout sessions were initialized using only a checkoutId:

neon.startEmbeddedCheckout({
  checkoutId: "40e6f131-7632-4fb2-81d6-0f00db0c5311"
});

Going forward, embedded integrations must also pass a checkoutToken returned from POST /checkout:

neon.startEmbeddedCheckout({
  checkoutId: "40e6f131-7632-4fb2-81d6-0f00db0c5311",
  checkoutToken: "ct_a1b2c3d4e5..."
});

No other integration changes are required. The end-user checkout experience remains unchanged.

Backend Change

The POST /checkout response now includes a token field:

{
  "checkoutId": "uuid",
  "token": "ct_a1b2c3d4e5...",
  "redirectUrl": "https://checkout.example.com/checkout/..."
}

Ensure your backend forwards the token value to the frontend when initializing Embedded Checkout.

Migration process

Update the Neon package or, if you are using the hosted Neon <script> tag (https://js.poweredbyneon.com/v1/neon.js), no action is required, as it is updated automatically.
Update your backend to return the token. The POST /checkout response now includes a token field. Make sure your backend forwards this value to the frontend.
Pass the token when starting Embedded Checkout.

Include the token value as checkoutToken when calling: startEmbeddedCheckout

Migration Timeline

Transition Phase (Current)

Both checkoutId and checkoutToken are accepted.
No breaking changes.

Post-Migration

checkoutToken will be required.
Initializing Embedded Checkout without a token will no longer be supported.

We recommend updating your integration during the transition period to avoid disruption.

Documentation

The Embedded Checkout documentation has been updated to reflect the new required parameter.