Skip to main content

Migrate to Drop-in Checkout

Use Drop-in when you want the fastest path away from Widget V3 and can accept a Purse-managed checkout UI.

Choose Drop-in if​

  • you need a ready-to-use checkout with minimal setup
  • you do not need custom widget layouts or custom widget types
  • you want to keep a simple pay-button flow
  • you want to keep the integration surface small

What changes from Widget V3​

Widget V3Drop-in Checkout
WidgetManager + createWidget()createDropinCheckout(session)
multiple widget interfaces and layoutsone checkout instance with built-in UI
custom assets, translations, and layout tuninglimited theme customization
widget-specific rendering logicPurse renders the payment form and pay button
separate pay-button widgetbuilt-in pay button

Migration steps​

  1. Keep the client session flow. Drop-in still starts from the same Purse session data.
  2. Replace the Widget V3 script with the Drop-in SDK.
  3. Remove Widget V3 config such as interface, layout, and widget-specific mount logic.
  4. Mount one Drop-in instance into a container on your page.
  5. Remove the Widget V3 pay-button widget if you used one. Drop-in already includes its own CTA.
  6. Do not wire your own submit button around it. The built-in CTA triggers submitPayment().
const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
});

await dropin.mount(document.getElementById('purse-dropin'));

What you cannot keep​

  • multiple mounted widget screens
  • widget-specific layouts and custom navigation
  • your own pay button as the main payment trigger
  • widget-level asset, translation, and method-group customization
  • pre/post validate hooks and redirection override

Trade-offs​

  • less control over the checkout UI
  • fewer branding knobs than Widget V3
  • a single built-in payment flow instead of a composed widget stack
When Drop-in is not enough

If you need full control over the checkout layout or want to rebuild the full payment experience, use Headless Checkout instead.

Next steps​