Medusa setup

• An Open Border merchant account whose KYB review has been approved.
• A Medusa v2 store you can add modules to and deploy.
• A charge currency of USD, GBP, EUR, CAD, or AUD. The charge currency selects the Open Border legal entity; the shipping destination independently drives duty and tax.
• An HS tariff code available per product or variant, in metadata you can read at checkout. If your catalogue does not have them, classify the products through Open Border first and persist the codes back.
• HTTPS between the browser and your Medusa server, because the browser posts a payment token to it.

This integration needs two keys, and they are not interchangeable. Getting them the wrong way round is the most common setup mistake here.

Both keys must be on the same rail: sk_test_ with pk_test_, and sk_live_ with pk_live_. A test key reaches only test rails and a live key only live rails.

npm install @open-border/medusa-payment-openborder @open-border/js

The same packages are published to GitHub Packages under the @openborder scope if you prefer that registry. Those installs need npm configured for the scope and a token with package read access.

@openborder:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
always-auth=true

Put the keys in your Medusa server environment. OPENBORDER_API_URL is optional outside local development, because the client picks the API host from the key’s rail — pass it explicitly for local or internal staging.

OPENBORDER_API_URL=https://api-demo.openborderpayments.com
OPENBORDER_API_KEY=sk_test_...
OPENBORDER_PUBLISHABLE_KEY=pk_test_...

Then register the provider with the Medusa v2 Payment Module. The provider identifier is openborder; with the provider id also set to openborder, Medusa stores the resolved id as pp_openborder_openborder.

module.exports = {
  modules: [
    {
      resolve: '@medusajs/medusa/payment',
      options: {
        providers: [
          {
            resolve: '@open-border/medusa-payment-openborder/providers/openborder',
            id: 'openborder',
            options: {
              apiKey: process.env.OPENBORDER_API_KEY,
              baseUrl: process.env.OPENBORDER_API_URL,
            },
          },
        ],
      },
    },
  ],
};

Now wire the checkout. The flow is quote-before-pay, in four moves: build the line items, quote duty and tax on the server, collect the card in the browser, then hand the token and the quote id back to the payment session.

const openBorderLineItems = cart.items.map((item) => ({
  sku: item.variant?.sku,
  description: item.title,
  quantity: item.quantity,
  unit_amount: item.unit_price,
  hs_code: item.metadata?.hs_code,
}));

const {
  createOpenBorderApiClient,
  OpenBorderTaxProvider,
} = require('@open-border/medusa-payment-openborder');

const openBorder = createOpenBorderApiClient({
  apiKey: process.env.OPENBORDER_API_KEY,
  baseUrl: process.env.OPENBORDER_API_URL,
});
const taxProvider = new OpenBorderTaxProvider(openBorder);

const quote = await taxProvider.getTaxLines(openBorderLineItems, {
  destination_country: shippingAddress.country_code.toUpperCase(),
  destination_postal_code: shippingAddress.postal_code,
  currency: cart.currency_code.toUpperCase(),
  shipping_amount: cart.shipping_total,
  customer: { email: cart.email },
});

quote.amount_breakdown.total is the landed-cost total to show the buyer before you collect a card. quote.tax_quote_id must travel with the payment session so Open Border can revalidate the quote when it creates the payment intent.

<div id="openborder-checkout"></div>
<script src="https://unpkg.com/@open-border/js"></script>
<script>
  const checkout = OpenBorder(window.OPENBORDER_PUBLISHABLE_KEY, {
    apiBaseUrl: window.OPENBORDER_API_URL,
  });

  checkout.mount('#openborder-checkout', {
    currency: quote.amount_breakdown.currency,
    amount: quote.amount_breakdown.total,
    billingDetails: {
      email: cart.email,
      name: cart.shipping_address?.first_name,
      address: cart.shipping_address,
    },
    onSuccess: async ({ paymentMethodId }) => {
      await fetch('/store/checkout/openborder-payment-method', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          cart_id: cart.id,
          payment_method: paymentMethodId,
          tax_quote_id: quote.tax_quote_id,
        }),
      });
    },
    onError: (message) => console.error(message),
  });
</script>

If your storefront sends a Content-Security-Policy, it must allow the payment processor’s browser SDK or the element silently fails to render. Allow script-src and frame-src for https://js.stripe.com, plus the wallet origins if you offer Apple Pay or Google Pay.

const sessionData = {
  cart_id: cart.id,
  payment_method: paymentMethodId,
  openborder_tax_quote_id: quote.tax_quote_id,
  amount_breakdown: quote.amount_breakdown,
  shipping_amount: cart.shipping_total,
  merchant_reference: cart.id,
  customer: {
    email: cart.email,
    name: `${cart.shipping_address.first_name} ${cart.shipping_address.last_name}`.trim(),
  },
  billing_address: toOpenBorderAddress(cart.billing_address ?? cart.shipping_address),
  shipping_address: toOpenBorderAddress(cart.shipping_address),
  line_items: openBorderLineItems,
  metadata: { medusa_cart_id: cart.id },
};

Until it lands, read server truth explicitly. The provider’s status lookup reads the current Open Border payment-intent status and owns no local money state, so it is safe to call whenever you need to know where a payment actually stands.

• Read payment status from Open Border before you treat an order as paid in any workflow that matters — do not infer it from the fact that a session was created.
• Treat the Open Border payment intent, transaction snapshot, and amount breakdown as the authoritative money record. Medusa is not the source of truth for money here.
• If a create call fails at the transport layer, the outcome is unknown: retry with the same idempotency key rather than building a new request. The provider derives its keys from persisted workflow identity, not from a volatile per-attempt key, so a plain retry of the same operation is safe.

1. 1 Successful payment Run a cart through with card 4242 4242 4242 4242, any future expiry, any CVC. Use test cards from the payment processor account attached to the resolved Open Border entity, and confirm the publishable key is on the same test rail as the secret key.
2. 2 Confirm the amounts reconcile The provider derives the merchandise subtotal from sum(quantity * unit_amount), because Medusa’s amount is the full payment-collection total including shipping and any quoted duty and tax. Without a quote, that total must equal subtotal plus shipping. With a quote, the provider checks the retained breakdown’s total, subtotal, shipping, and currency before authorising.
3. 3 Decline Repeat with card 4000 0000 0000 0002 and confirm your checkout surfaces a safe error and does not place a paid order.
4. 4 Persist the receipt fields The package does not write these into Medusa order metadata for you. Do it in your own order-completion workflow, or support staff will have no way to reconcile a Medusa order to an Open Border transaction.

• openborder_payment_intent_id
• openborder_status
• entity — the Open Border entity resolved from the charge currency
• amount_breakdown — subtotal, shipping, tax, duty, total, and currency
• tax_quote_id
• client_secret, when the payment flow returned one

1. 1 Swap both keys together Move to sk_live_ on the server and pk_live_ in the browser at the same time. A mismatched pair fails rather than half-working, but swapping only one is still the easiest way to waste an afternoon.
2. 2 Point at the production API Set OPENBORDER_API_URL=https://api.openborderpayments.com, or drop the variable entirely and let the client resolve the host from the live key’s rail.
3. 3 Audit what reaches the browser Grep your built storefront bundle and your server-rendered HTML for sk_ before you deploy. This is the one mistake in this integration you cannot walk back.
4. 4 Confirm your CSP allows the processor SDK A production CSP that blocks the browser SDK makes the card element silently fail to render — it does not raise an obvious error.
5. 5 Confirm every product carries an HS code A quote cannot be created for a line item without one. Check the real catalogue, not a fixture.
6. 6 Take one small real payment and refund it Confirm the intent, the breakdown, and your persisted receipt fields all look right before opening checkout to buyers.

Upgrade with npm as normal, but read the package changelog first: this package’s money-field conventions changed at 0.7.0, and a unit-convention change is not something a test suite in your storefront will necessarily catch. Update the payment-session and tax-provider inputs in the same change as the version bump.

To remove the integration, unregister the provider from medusa-config.ts, delete the checkout wiring, and uninstall both packages. Resolve every non-terminal payment first — Open Border remains the authoritative record for anything already charged, and removing the provider does not release an outstanding authorisation.

• Keep sk_ keys server-side, and expose only pk_ keys to browser code.
• Use test keys and the sandbox host until production activation is approved.
• Send payment tokens from the browser to your backend over HTTPS only.
• Never log a full API key, a payment method id, card data, or a customer address.