@swft-checkout/medusa

Swft Checkout plugin for Medusa v2. Integrates sub-200ms edge checkout into any Medusa storefront.

Installation

npm install @swft-checkout/medusa @swft-checkout/js

Plugin registration

In medusa-config.ts:

import { defineConfig } from '@medusajs/medusa'

export default defineConfig({
  plugins: [
    {
      resolve: '@swft-checkout/medusa',
      options: {
        merchantApiKey: process.env.SWFT_MERCHANT_API_KEY,
        webhookSecret:  process.env.SWFT_WEBHOOK_SECRET,
      },
    },
  ],
})

Usage in a custom API route or storefront

import { SwftSessionService } from '@swft-checkout/medusa'

// In your checkout route:
const swft = new SwftSessionService({
  merchantApiKey: process.env.SWFT_MERCHANT_API_KEY!,
})

const session = await swft.createFromCart(cart)
// Redirect the customer to session.sessionUrl

The cart object should be a fully populated Medusa Cart with items, shipping_methods, and customer populated.

Webhook setup

The plugin registers POST /webhooks/swft automatically. When Swft fires a payment_succeeded event, this route verifies the signature and calls completeCart on the matching Medusa cart, triggering order creation via Medusa's standard workflow.

Steps:

1. Deploy your Medusa backend
2. In your Swft merchant dashboard, set the webhook URL to https://your-medusa-url.com/webhooks/swft
3. Copy the webhook signing secret from Swft and set SWFT_WEBHOOK_SECRET in your environment

Environment variables

| Variable | Description | |---|---| | SWFT_MERCHANT_API_KEY | Your Swft merchant API key — from swft.co.uk/dashboard | | SWFT_WEBHOOK_SECRET | Webhook signing secret — from Swft merchant settings |

Optional: auto-create sessions on cart creation

The plugin ships a cart-created subscriber that eagerly creates a Swft session whenever a Medusa cart is created and stores swft_session_url in cart metadata.

To enable it, import and register the subscriber in your Medusa project's src/subscribers/ directory or let Medusa auto-discover it from the plugin's subscribers/ folder.

When enabled, your storefront can read cart.metadata.swft_session_url and redirect immediately without an extra API call.

Module extensions via extensions

Swft Gifts, Drops, Bumps, and Funnels all pass data through the extensions field on the session. When using SwftSessionService.createFromCart, the medusa_cart_id is set automatically. To pass additional module data:

// The session service sets medusa_cart_id — add your own fields by extending
// the cart object or by calling createSession from @swft-checkout/js directly with:
// extensions: { medusa_cart_id: cart.id, swft_bump_id: 'bump_xyz', ... }

Architecture

Storefront              Medusa Backend              Swft Edge
---------               --------------              ----------
cart.create()    -->    cart-created subscriber -->  createSession()
                        (stores session URL in       (returns sessionUrl)
                         cart metadata)

checkout         -->    read cart.metadata
                        .swft_session_url
                 -->    redirect to sessionUrl  -->  Swft Checkout UI

payment done     <--    POST /webhooks/swft     <--  payment_succeeded event
                        verifySwftWebhook()
                        completeCart(cartId)
                        --> order created

License

MIT